@driftengine/core 4.8.3 → 4.8.5

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

@@ -16,6 +16,8 @@ import type { SurfaceMaterial } from './surfaceTexture.ts';
 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;

package/dist/render/cutoutCaster.js

@@ -1,6 +1,7 @@
 const answer = {
     albedo: null,
     cutoff: 0,
+    dithered: 0,
     u: 1,
     v: 1,
     uOffset: 0,
@@ -16,6 +17,7 @@ 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;

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/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);
+}

package/dist/render/hairLobes.d.ts

@@ -0,0 +1,70 @@
+/**
+ * The hair model's lobes, as `shaders/flat/hair.ts` computes them: the reference its tests hold the
+ * arithmetic to, and nothing at run time calls it.
+ *
+ * **A strand is a rough dielectric cylinder, index 1.55, after Marschner et al. 2003 in the
+ * real-time form Karis gave in 2016.** Light leaves it three ways, each a longitudinal Gaussian in
+ * `sinθi + sinθo` — the angles of light and eye out of the plane normal to the strand — times an
+ * azimuthal term in φ, the turn between them around it:
+ *
+ * - **R**, reflected off the surface: white, and shifted toward the root by twice the tilt of the
+ *   cuticle's scales, which point toward the tip;
+ * - **TT**, through the strand and out: the glow of a backlit head, shifted toward the tip by the
+ *   tilt, half as wide, and tinted by the fibre for the path it took;
+ * - **TRT**, reflected once inside: the coloured second highlight, three tilts toward the tip and
+ *   twice as wide;
+ *
+ * and a fourth, the light scattered through many strands, as a wrapped diffuse against a normal
+ * turned toward the eye across the strand, tinted by a root of the fibre's colour.
+ *
+ * **The tangent runs from root to tip**, and the tilt is positive for a strand authored that way. A
+ * card authored the other way round swaps its two highlights' ends, and takes a negative shift.
+ *
+ * **In this engine's light units.** A lamp's diffuse here is `albedo · cosθ` with no 1/π, so the
+ * published lobes, which are per unit irradiance, are multiplied by π; the scatter term's 1/π cancels.
+ * **What it gives up** is the fit's own: these are Karis's approximations to the azimuthal
+ * integrals, not the integrals, and they do not conserve energy exactly — the tests hold the sum
+ * under what a strand receives.
+ */
+import type { Vec3 } from '../math/color.ts';
+/** Schlick's base for a strand at index 1.55: `((1 − n) / (1 + n))²`. */
+export declare const HAIR_F0: number;
+/**
+ * The narrowest longitudinal width a strand is drawn at, in radians.
+ *
+ * **Below every measured fibre**: Marschner gives the reflected lobe 5° to 10°, and this is about
+ * 3°, so no real hair is clamped. What it stops is a roughness of 0 making a Gaussian narrower than
+ * a pixel can sample — the speckle `MIN_LOBE_ALPHA` argues against for the standard lobe.
+ */
+export declare const HAIR_MIN_BETA = 0.05;
+/**
+ * The scatter term's answer to light arriving evenly from every side, per unit of it: the term's
+ * shape integrated over the sphere and divided by π, which is how this engine's lamp units add up.
+ *
+ * Derived: the wrapped half `(N·L + 1) / 4` averages 1/4 over the sphere, `1 − |T·L|` averages 1/2,
+ * and the shape is `mix(wrapped, 1 − |T·L|, 0.33)`, so its mean is 0.67 · 0.25 + 0.33 · 0.5 = 0.3325
+ * and its integral 4π times that. Over π: **1.33**.
+ */
+export declare const HAIR_SCATTER_SPHERE = 1.33;
+/** A longitudinal lobe: a normalised Gaussian of width `beta` at `x` from its centre. */
+export declare function hairLongitudinal(beta: number, x: number): number;
+/** Schlick's Fresnel for the strand at a cosine, clamped to the unit interval. */
+export declare function hairFresnel(cosine: number): number;
+/** Where `hairLight` leaves its answer: R, then TT, TRT and the scatter, each a colour. */
+export declare const HAIR_OUT: {
+    readonly r: 0;
+    readonly tt: 1;
+    readonly trt: 4;
+    readonly scatter: 7;
+    readonly length: 10;
+};
+/**
+ * One light on a strand, in lamp units and unshadowed, into `out` (`HAIR_OUT`'s layout: R is grey,
+ * the rest colours). `tangent`, `toLight` and `toEye` are unit vectors but for a tangent that could
+ * not be made one, which comes in as zeros; `fibre` is the base colour.
+ *
+ * **A lamp with a size widens every lobe by the angle it subtends**, `sourceRadius / 2·dist` as
+ * `sphereLobe` takes it, and the lobes are normalised Gaussians, so a wider one carries the same
+ * light rather than more. The sun passes zeros.
+ */
+export declare function hairLight(tangent: ArrayLike<number>, toLight: ArrayLike<number>, toEye: ArrayLike<number>, fibre: Vec3, roughness: number, shift: number, scatter: number, backlit: number, sourceRadius: number, dist: number, out: Float64Array): void;

package/dist/render/hairLobes.js

@@ -0,0 +1,120 @@
+/** Schlick's base for a strand at index 1.55: `((1 − n) / (1 + n))²`. */
+export const HAIR_F0 = ((1 - 1.55) / (1 + 1.55)) ** 2;
+/**
+ * The narrowest longitudinal width a strand is drawn at, in radians.
+ *
+ * **Below every measured fibre**: Marschner gives the reflected lobe 5° to 10°, and this is about
+ * 3°, so no real hair is clamped. What it stops is a roughness of 0 making a Gaussian narrower than
+ * a pixel can sample — the speckle `MIN_LOBE_ALPHA` argues against for the standard lobe.
+ */
+export const HAIR_MIN_BETA = 0.05;
+/**
+ * The scatter term's answer to light arriving evenly from every side, per unit of it: the term's
+ * shape integrated over the sphere and divided by π, which is how this engine's lamp units add up.
+ *
+ * Derived: the wrapped half `(N·L + 1) / 4` averages 1/4 over the sphere, `1 − |T·L|` averages 1/2,
+ * and the shape is `mix(wrapped, 1 − |T·L|, 0.33)`, so its mean is 0.67 · 0.25 + 0.33 · 0.5 = 0.3325
+ * and its integral 4π times that. Over π: **1.33**.
+ */
+export const HAIR_SCATTER_SPHERE = 1.33;
+/** How much the scatter term leans toward the strand's own direction rather than the pseudo-normal. */
+const KAJIYA_SHARE = 0.33;
+/** A longitudinal lobe: a normalised Gaussian of width `beta` at `x` from its centre. */
+export function hairLongitudinal(beta, x) {
+    return Math.exp((-0.5 * x * x) / (beta * beta)) / (Math.sqrt(2 * Math.PI) * beta);
+}
+/** Schlick's Fresnel for the strand at a cosine, clamped to the unit interval. */
+export function hairFresnel(cosine) {
+    const c = 1 - Math.min(Math.max(cosine, 0), 1);
+    return HAIR_F0 + (1 - HAIR_F0) * c * c * c * c * c;
+}
+function dot(a, b) {
+    return (a[0] * b[0] +
+        a[1] * b[1] +
+        a[2] * b[2]);
+}
+const clamp = (x, low, high) => Math.min(Math.max(x, low), high);
+/** Where `hairLight` leaves its answer: R, then TT, TRT and the scatter, each a colour. */
+export const HAIR_OUT = { r: 0, tt: 1, trt: 4, scatter: 7, length: 10 };
+/**
+ * One light on a strand, in lamp units and unshadowed, into `out` (`HAIR_OUT`'s layout: R is grey,
+ * the rest colours). `tangent`, `toLight` and `toEye` are unit vectors but for a tangent that could
+ * not be made one, which comes in as zeros; `fibre` is the base colour.
+ *
+ * **A lamp with a size widens every lobe by the angle it subtends**, `sourceRadius / 2·dist` as
+ * `sphereLobe` takes it, and the lobes are normalised Gaussians, so a wider one carries the same
+ * light rather than more. The sun passes zeros.
+ */
+export function hairLight(tangent, toLight, toEye, fibre, roughness, shift, scatter, backlit, sourceRadius, dist, out) {
+    const sinI = clamp(dot(tangent, toLight), -1, 1);
+    const sinO = clamp(dot(tangent, toEye), -1, 1);
+    /*
+     * The half difference angle, rounded to single precision as the device holds it: at its limit,
+     * light and eye at opposite ends of the strand, that is π/2 rounded up, whose cosine is −4.4e-8
+     * rather than double precision's +6e-17 — and the transmitted powers divide by it. The floor is
+     * for the device's number, and the rounding is what lets a test here see it.
+     */
+    const cosD = Math.max(Math.cos(Math.fround(0.5 * Math.abs(Math.asin(sinO) - Math.asin(sinI)))), 1e-3);
+    let lp2 = 0;
+    let vp2 = 0;
+    let lpvp = 0;
+    for (let c = 0; c < 3; c++) {
+        const lp = toLight[c] - sinI * tangent[c];
+        const vp = toEye[c] - sinO * tangent[c];
+        lp2 += lp * lp;
+        vp2 += vp * vp;
+        lpvp += lp * vp;
+    }
+    const cosPhi = lpvp / Math.sqrt(lp2 * vp2 + 1e-4);
+    const cosHalfPhi = Math.sqrt(clamp(0.5 + 0.5 * cosPhi, 0, 1));
+    const beta = Math.max(roughness * roughness, HAIR_MIN_BETA);
+    const grow = sourceRadius / Math.max(2 * dist, 1e-3);
+    const x = sinI + sinO;
+    const r = hairLongitudinal(beta + grow, x + 2 * shift) *
+        0.25 *
+        cosHalfPhi *
+        hairFresnel(Math.sqrt(clamp(0.5 + 0.5 * dot(toLight, toEye), 0, 1)));
+    const a = 1 / (1.19 / cosD + 0.36 * cosD);
+    const h = cosHalfPhi * (1 + a * (0.6 - 0.8 * cosPhi));
+    const fTT = hairFresnel(cosD * Math.sqrt(clamp(1 - h * h, 0, 1)));
+    const tt = hairLongitudinal(0.5 * beta + grow, x - shift) *
+        Math.exp(-3.65 * cosPhi - 3.98) *
+        (1 - fTT) *
+        (1 - fTT) *
+        backlit;
+    const ttPower = (0.5 * Math.sqrt(clamp(1 - h * h * a * a, 0, 1))) / cosD;
+    const fTRT = hairFresnel(0.5 * cosD);
+    const trt = hairLongitudinal(2 * beta + grow, x - 3 * shift) *
+        Math.exp(17 * cosPhi - 16.78) *
+        (1 - fTRT) *
+        (1 - fTRT) *
+        fTRT;
+    const trtPower = 0.8 / cosD;
+    let across0 = toEye[0] - tangent[0] * sinO;
+    let across1 = toEye[1] - tangent[1] * sinO;
+    let across2 = toEye[2] - tangent[2] * sinO;
+    const acrossLength = Math.hypot(across0, across1, across2);
+    if (acrossLength > 1e-4) {
+        across0 /= acrossLength;
+        across1 /= acrossLength;
+        across2 /= acrossLength;
+    }
+    const wrapped = clamp((across0 * toLight[0] +
+        across1 * toLight[1] +
+        across2 * toLight[2] +
+        1) /
+        4, 0, 1);
+    const shape = wrapped + (1 - Math.abs(sinI) - wrapped) * KAJIYA_SHARE;
+    out[HAIR_OUT.r] = Math.PI * r;
+    for (let c = 0; c < 3; c++) {
+        /*
+         * Above zero, so the device's `pow` never forms the logarithm of zero: an infinity in the
+         * middle of an expression is something a shader compiler may assume never happens. Nothing in
+         * double precision can show the difference, so no test here does.
+         */
+        const colour = Math.max(fibre[c], 1e-4);
+        out[HAIR_OUT.tt + c] = Math.PI * tt * colour ** ttPower;
+        out[HAIR_OUT.trt + c] = Math.PI * trt * colour ** trtPower;
+        out[HAIR_OUT.scatter + c] = Math.sqrt(fibre[c]) * scatter * shape;
+    }
+}