@driftengine/core 4.8.2 → 4.8.4

package/dist/render/clothPlacement.js

@@ -0,0 +1,85 @@
+/**
+ * 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.
+ */
+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, a, b, c, out) {
+    const ex = particles[b * 3] - particles[a * 3];
+    const ey = particles[b * 3 + 1] - particles[a * 3 + 1];
+    const ez = particles[b * 3 + 2] - particles[a * 3 + 2];
+    const fx = particles[c * 3] - particles[a * 3];
+    const fy = particles[c * 3 + 1] - particles[a * 3 + 1];
+    const fz = particles[c * 3 + 2] - particles[a * 3 + 2];
+    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, rest, a, b, c, u, v, offset, restNormal, out) {
+    if (a === b && b === c) {
+        out.position[0] = now[a * 3];
+        out.position[1] = now[a * 3 + 1];
+        out.position[2] = now[a * 3 + 2];
+        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] * w +
+                now[b * 3 + k] * u +
+                now[c * 3 + k] * v +
+                NOW[6 + k] * offset;
+    }
+    /* Turned by now × restᵀ: the rest normal in the rest frame's terms, rebuilt in the frame now. */
+    const t = REST[0] * restNormal[0] +
+        REST[1] * restNormal[1] +
+        REST[2] * restNormal[2];
+    const s = REST[3] * restNormal[0] +
+        REST[4] * restNormal[1] +
+        REST[5] * restNormal[2];
+    const n = REST[6] * restNormal[0] +
+        REST[7] * restNormal[1] +
+        REST[8] * restNormal[2];
+    for (let k = 0; k < 3; k++) {
+        out.normal[k] =
+            NOW[k] * t + NOW[3 + k] * s + NOW[6 + k] * n;
+    }
+}

package/dist/render/compressedSource.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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 declare function compressedLayers(sources: readonly SurfaceSource[]): readonly CompressedTextureSource[] | null;
+/** Bytes per 4x4 block. */
+export declare const BLOCK_BYTES: Readonly<Record<BlockFormat, number>>;
+/** Whether `source` is a compressed source rather than an image. */
+export declare function isCompressedSource(source: unknown): source is CompressedTextureSource;
+/** The format a device would have to offer, or null for one with no sRGB form. */
+export declare function compressedFormatName(format: BlockFormat, srgb: boolean): CompressedTextureFormat | null;
+/**
+ * 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 declare function uploadsCompressed(format: BlockFormat, srgb: boolean, width: number, height: number, available: readonly CompressedTextureFormat[]): boolean;
+/**
+ * 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 declare function compressedLevels(layers: readonly CompressedTextureSource[]): number;
+/** What a refusal names: the format, its colour space, and what the device offers instead. */
+export declare function compressedRefusal(format: BlockFormat, srgb: boolean, width: number, height: number, available: readonly CompressedTextureFormat[]): string;
+/** The format name and level count blocks upload as here, or a refusal naming why they cannot. */
+export declare function planBlocks(blocks: readonly CompressedTextureSource[], srgb: boolean, compressed: readonly CompressedTextureFormat[]): {
+    readonly name: CompressedTextureFormat;
+    readonly levels: number;
+};
+/**
+ * `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 declare function refuseBlockUpdate(format: BlockFormat | null): void;

package/dist/render/compressedSource.js

@@ -0,0 +1,138 @@
+/**
+ * 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.
+ */
+/**
+ * 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) {
+    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;
+}
+/** Bytes per 4x4 block. */
+export const BLOCK_BYTES = {
+    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) {
+    const candidate = source;
+    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, srgb) {
+    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, srgb, width, height, available) {
+    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, width, height, level) {
+    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) {
+    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];
+        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].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, srgb, width, height, available) {
+    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, srgb, compressed) {
+    const { format, width, height } = blocks[0];
+    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) {
+    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/dist/render/cutoutCaster.d.ts

@@ -12,12 +12,16 @@
  * reads it and binds before it asks again.
  */
 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;
 }
 /** The cutout `material` casts, or null for an ordinary caster. */
 export declare function cutoutOf<Texture>(material: SurfaceMaterial<Texture> | null | undefined): CutoutCaster<Texture> | null;

package/dist/render/cutoutCaster.js

@@ -1,8 +1,11 @@
 const answer = {
     albedo: null,
     cutoff: 0,
+    dithered: 0,
     u: 1,
     v: 1,
+    uOffset: 0,
+    vOffset: 0,
 };
 /** The cutout `material` casts, or null for an ordinary caster. */
 export function cutoutOf(material) {
@@ -14,7 +17,10 @@ export function cutoutOf(material) {
         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;
 }

package/dist/render/cutoutDither.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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 declare const CUTOUT_RESOLVE_CODE: Readonly<Record<CutoutResolve, number>>;
+/**
+ * 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 declare function resolveCutout(mode: CutoutMode, temporal: boolean, samples: number): CutoutResolve;
+/**
+ * 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 declare function cutoutShare(alpha: number, cutoff: number): number;
+/**
+ * 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 declare function ditherThreshold(x: number, y: number, frame: number): number;
+/**
+ * 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 declare const CUTOUT_DITHER_GLSL: string;

package/dist/render/cutoutDither.js

@@ -0,0 +1,90 @@
+/**
+ * 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.
+ */
+/** The shader's number for a resolve. */
+export const CUTOUT_RESOLVE_CODE = 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, temporal, samples) {
+    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, cutoff) {
+    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, y, frame) {
+    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/dist/render/decalPass.js

@@ -4,6 +4,7 @@ import { DEPTH_01_TO_CLIP } from './lightVolumeDraw.js';
 import { compileProgram, uniformLocations } from './shader.js';
 import { DECAL_PROJECT_FRAG } from './shaders/decalProject.js';
 import { FULLSCREEN_VERT } from './shaders/fullscreen.js';
+import { blendKeeping } from './sceneCoverage.js';
 /**
  * Drawn decals on WebGL2: one scissored triangle per mark, multiplied into the finished scene.
  *
@@ -54,7 +55,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
            the renderer leaves that wherever its last pass finished. `OitPass` records what leaving it

package/dist/render/eyeRefraction.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 declare const CORNEA_F0: number;
+/** How slowly a refracted ray may descend toward the iris plane before it is held there. */
+export declare const EYE_MIN_DESCENT = 0.001;
+/** GLSL's `refract`, into `out`: the transmitted direction, or zeros past total internal reflection. */
+export declare function refract(incident: Vec3, normal: Vec3, eta: number, out: Float64Array): void;
+/**
+ * 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 declare function eyeRefractionShift(toEye: Vec3, normal: Vec3, axis: Vec3, ior: number, height: number, out: Float64Array): void;
+/**
+ * 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 declare function irisMask(u: number, v: number, irisRadius: number, edge: number): number;

package/dist/render/eyeRefraction.js

@@ -0,0 +1,40 @@
+/** 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, normal, eta, out) {
+    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] - s * normal[c];
+}
+/**
+ * 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, normal, axis, ior, height, out) {
+    const ray = new Float64Array(3);
+    refract([-toEye[0], -toEye[1], -toEye[2]], normal, 1 / ior, ray);
+    const descent = Math.max(-(ray[0] * axis[0] + ray[1] * axis[1] + ray[2] * axis[2]), EYE_MIN_DESCENT);
+    const reach = height / descent;
+    const along = (ray[0] * axis[0] + ray[1] * axis[1] + ray[2] * axis[2]) *
+        reach;
+    for (let c = 0; c < 3; c++)
+        out[c] = ray[c] * 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, v, irisRadius, edge) {
+    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/dist/render/glCompressed.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 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 declare function glCompressedFormats(gl: WebGL2RenderingContext): CompressedTextureFormat[];
+/**
+ * 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 declare function uploadCompressedArray(gl: WebGL2RenderingContext, name: CompressedTextureFormat, layers: readonly CompressedTextureSource[], levels: number): void;

package/dist/render/glCompressed.js

@@ -0,0 +1,53 @@
+/** The constants each extension defines, written out so a missing extension cannot be read for one. */
+const INTERNAL = {
+    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 = [
+    ['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) {
+    const out = [];
+    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, name, layers, levels) {
+    const first = layers[0];
+    for (let level = 0; level < levels; level++) {
+        let size = 0;
+        for (const layer of layers)
+            size += layer.levels[level].length;
+        const data = new Uint8Array(size);
+        let at = 0;
+        for (const layer of layers) {
+            const bytes = layer.levels[level];
+            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);
+}