@driftengine/core 4.8.3 → 4.8.4

package/dist/render/skinScatter.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The skin model's arithmetic, as `shaders/flat/skin.ts` computes it: the reference its tests hold
+ * the fit to, and nothing at run time calls it.
+ *
+ * **Pre-integrated, after Penner 2011, with the profile integrated rather than looked up.** Light
+ * entering skin leaves it a little way off, so on a curved surface a point is lit by its
+ * neighbours' `N·L` as well as its own: the clamped cosine averaged around a ring of the surface's
+ * curvature, weighted by the diffusion profile at each neighbour's distance. The profile is Burley's
+ * normalised diffusion, one per channel, at a scatter distance `d` — the model's `radius` times its
+ * scatter colour — projected onto the ring's plane, as a cylinder's cross-section sees it. The
+ * result depends on `N·L` and on one number per channel, `k = d × curvature`, and at `k = 0` it is
+ * Lambert's.
+ *
+ * **Fitted rather than tabulated**, so no seventeenth sampler and no image: the ring average is the
+ * clamped cosine convolved with an angular kernel, so it splits into the cosine's first harmonic —
+ * scaled by one number, `κ₁(k)` — and a smoothed `|cos θ|` carrying every even harmonic:
+ *
+ *     D(c, k) = ½ (κ₁ c + A √(c² + ε²) + B)
+ *
+ * with `κ₁`, `A`, `ε` and `B` closed forms in `k` that are exactly `1, 1, 0, 0` at `k = 0`. The
+ * test measures it against the integral done numerically: **worst 0.0105 over `k` to 10**, beyond
+ * which the shader holds `k` — a scatter ten times the surface's own radius, where the answer is
+ * nearly flat already.
+ */
+/** Schlick's base for skin, at index 1.4: `((1 − n) / (1 + n))²`. */
+export declare const SKIN_F0: number;
+/** The largest `k` the fit is held to, and where the shader clamps it. */
+export declare const SKIN_MAX_K = 10;
+/**
+ * The fit's eight numbers, found by minimising its worst error against the numeric integral over
+ * `c` in [−1, 1] and `k` in (0, 10]:
+ *
+ * - `kappa`: `κ₁ = (1 + a k² + b k³)^(−1/6)` — the first harmonic's share, quadratic at zero and
+ *   falling as `1/√k`, as the integral's does;
+ * - `spread`: `A = (1 + a k³)^(−1/6)`;
+ * - `soften`: `ε = a k / (1 + b k)`, how far `|c|` is rounded at the terminator;
+ * - `floor`: `B = (1 − A)(a + b (1 − A))`, the even part's floor as `A` gives up `|c|`.
+ */
+export declare const SKIN_FIT: {
+    readonly kappa: readonly [22.6772, 101.349];
+    readonly spread: 838.87;
+    readonly soften: readonly [1.3081, 3.65743];
+    readonly floor: readonly [0.508537, 0.129496];
+};
+/** The ring-averaged `N·L` for one channel: `c` is `N·L`, `k` that channel's scatter × curvature. */
+export declare function skinRing(c: number, k: number): number;
+/**
+ * How far into a penumbra skin's light reaches, as a width the shadow is assumed to have: the
+ * lamp loop reads a shadow where its derivative cannot be taken, so its width in the world is not
+ * known there. Two centimetres is a soft edge across a face.
+ */
+export declare const SKIN_PENUMBRA_WIDTH = 0.02;
+/**
+ * A shadow on skin, one channel at scatter distance `d`: the shadow's own value raised to
+ * `1 / (1 + d / width)`, so light reaches further into the penumbra the further that channel
+ * travels beneath the surface — red furthest, which is the red edge a shadow on skin has — and a
+ * shadow stays whole at 0 and absent at 1. **What it gives up** is the profile itself: Penner
+ * convolves a sharpened shadow with it, which needs the penumbra's width in the world and hardens
+ * the narrow channels' edge where nothing widened the map to make room.
+ */
+export declare function skinPenumbra(shadow: number, d: number): number;
+/**
+ * Light through a thin part, one channel: `transmission × exp(−thickness / d)` of the light behind,
+ * by how squarely it is behind. A part as thick as its curvature's diameter — an ear's rim at a few
+ * millimetres, a cheek at ten centimetres — passes red through the one and nothing through the other.
+ */
+export declare function skinTransmission(backNdl: number, thickness: number, d: number, transmission: number): number;

package/dist/render/skinScatter.js

@@ -0,0 +1,80 @@
+/**
+ * The skin model's arithmetic, as `shaders/flat/skin.ts` computes it: the reference its tests hold
+ * the fit to, and nothing at run time calls it.
+ *
+ * **Pre-integrated, after Penner 2011, with the profile integrated rather than looked up.** Light
+ * entering skin leaves it a little way off, so on a curved surface a point is lit by its
+ * neighbours' `N·L` as well as its own: the clamped cosine averaged around a ring of the surface's
+ * curvature, weighted by the diffusion profile at each neighbour's distance. The profile is Burley's
+ * normalised diffusion, one per channel, at a scatter distance `d` — the model's `radius` times its
+ * scatter colour — projected onto the ring's plane, as a cylinder's cross-section sees it. The
+ * result depends on `N·L` and on one number per channel, `k = d × curvature`, and at `k = 0` it is
+ * Lambert's.
+ *
+ * **Fitted rather than tabulated**, so no seventeenth sampler and no image: the ring average is the
+ * clamped cosine convolved with an angular kernel, so it splits into the cosine's first harmonic —
+ * scaled by one number, `κ₁(k)` — and a smoothed `|cos θ|` carrying every even harmonic:
+ *
+ *     D(c, k) = ½ (κ₁ c + A √(c² + ε²) + B)
+ *
+ * with `κ₁`, `A`, `ε` and `B` closed forms in `k` that are exactly `1, 1, 0, 0` at `k = 0`. The
+ * test measures it against the integral done numerically: **worst 0.0105 over `k` to 10**, beyond
+ * which the shader holds `k` — a scatter ten times the surface's own radius, where the answer is
+ * nearly flat already.
+ */
+/** Schlick's base for skin, at index 1.4: `((1 − n) / (1 + n))²`. */
+export const SKIN_F0 = ((1 - 1.4) / (1 + 1.4)) ** 2;
+/** The largest `k` the fit is held to, and where the shader clamps it. */
+export const SKIN_MAX_K = 10;
+/**
+ * The fit's eight numbers, found by minimising its worst error against the numeric integral over
+ * `c` in [−1, 1] and `k` in (0, 10]:
+ *
+ * - `kappa`: `κ₁ = (1 + a k² + b k³)^(−1/6)` — the first harmonic's share, quadratic at zero and
+ *   falling as `1/√k`, as the integral's does;
+ * - `spread`: `A = (1 + a k³)^(−1/6)`;
+ * - `soften`: `ε = a k / (1 + b k)`, how far `|c|` is rounded at the terminator;
+ * - `floor`: `B = (1 − A)(a + b (1 − A))`, the even part's floor as `A` gives up `|c|`.
+ */
+export const SKIN_FIT = {
+    kappa: [22.6772, 101.349],
+    spread: 838.87,
+    soften: [1.3081, 3.65743],
+    floor: [0.508537, 0.129496],
+};
+/** The ring-averaged `N·L` for one channel: `c` is `N·L`, `k` that channel's scatter × curvature. */
+export function skinRing(c, k) {
+    const q = Math.min(Math.max(k, 0), SKIN_MAX_K);
+    const k2 = q * q;
+    const kappa = (1 + SKIN_FIT.kappa[0] * k2 + SKIN_FIT.kappa[1] * k2 * q) ** (-1 / 6);
+    const spread = (1 + SKIN_FIT.spread * k2 * q) ** (-1 / 6);
+    const soften = (SKIN_FIT.soften[0] * q) / (1 + SKIN_FIT.soften[1] * q);
+    const given = 1 - spread;
+    const floor = given * (SKIN_FIT.floor[0] + SKIN_FIT.floor[1] * given);
+    return 0.5 * (kappa * c + spread * Math.sqrt(c * c + soften * soften) + floor);
+}
+/**
+ * How far into a penumbra skin's light reaches, as a width the shadow is assumed to have: the
+ * lamp loop reads a shadow where its derivative cannot be taken, so its width in the world is not
+ * known there. Two centimetres is a soft edge across a face.
+ */
+export const SKIN_PENUMBRA_WIDTH = 0.02;
+/**
+ * A shadow on skin, one channel at scatter distance `d`: the shadow's own value raised to
+ * `1 / (1 + d / width)`, so light reaches further into the penumbra the further that channel
+ * travels beneath the surface — red furthest, which is the red edge a shadow on skin has — and a
+ * shadow stays whole at 0 and absent at 1. **What it gives up** is the profile itself: Penner
+ * convolves a sharpened shadow with it, which needs the penumbra's width in the world and hardens
+ * the narrow channels' edge where nothing widened the map to make room.
+ */
+export function skinPenumbra(shadow, d) {
+    return Math.max(shadow, 0) ** (1 / (1 + d / SKIN_PENUMBRA_WIDTH));
+}
+/**
+ * Light through a thin part, one channel: `transmission × exp(−thickness / d)` of the light behind,
+ * by how squarely it is behind. A part as thick as its curvature's diameter — an ear's rim at a few
+ * millimetres, a cheek at ten centimetres — passes red through the one and nothing through the other.
+ */
+export function skinTransmission(backNdl, thickness, d, transmission) {
+    return transmission * Math.exp(-thickness / Math.max(d, 1e-6)) * Math.max(backNdl, 0);
+}

package/dist/render/skinnedClothRun.d.ts

@@ -0,0 +1,26 @@
+import type { SkinnedClothSetup } from '@driftengine/physics';
+import type { ClothParticlesHandle, RendererApi } from './backend/api.ts';
+/** A garment a renderer solves, from `createSkinnedCloth`. */
+export interface SkinnedClothSolver {
+    /** What `setCloth(binding, particles)` draws the garment's bound meshes by. */
+    readonly particles: ClothParticlesHandle;
+    /** Where the solver runs: on the device, or on the CPU beneath a backend without compute. */
+    readonly runsOn: 'device' | 'cpu';
+    /**
+     * One frame: the rig's pose — each joint's global matrix, model space, sixteen floats a joint,
+     * and the model matrix — and `dt` seconds, run as whole fixed steps; the particles at the frame's
+     * `alpha` are then what the frame draws. **Once a frame, before the draws**, as
+     * `updateClothParticles` is: a second in one frame would reach every draw of it on WebGPU.
+     */
+    step(globals: Float32Array, model: Float32Array, dt: number): void;
+    /**
+     * The air the cloth drags toward from the next step, world space, metres a second: the frame's
+     * sample of the scene's one `WindField`, so a garment moves with everything else in the air.
+     */
+    setWind(x: number, y: number, z: number): void;
+    /** Back to the skinned pose, settled, as a teleport resets it. */
+    reset(): void;
+    dispose(): void;
+}
+/** A garment for `renderer`, from a set-up checked by name. */
+export declare function createSkinnedCloth(renderer: RendererApi, setup: SkinnedClothSetup): SkinnedClothSolver;

package/dist/render/skinnedClothRun.js

@@ -0,0 +1,84 @@
+/**
+ * A skinned cloth for a renderer: `@driftengine/physics`' solver, run as compute on WebGPU — the
+ * particles never leave the device — and as `SkinnedCloth` on the CPU under WebGL2, which has no
+ * compute. One schedule, `ClothControl`, and the same kernels either way; what a frame draws is
+ * `particles`, through `setCloth(binding, cloth.particles)`.
+ *
+ * **A function rather than renderer methods, so a game pays for it only by importing it.** See
+ * `backend/webgpu/computeHost.ts` for the door it reaches the device through, and why.
+ *
+ * **The CPU fallback's cost**, measured on a desktop part: a few hundred particles are a
+ * millisecond a frame on the main thread, and 4,500 are twenty — a garment that size wants the
+ * device. The device solver ran 4,500 particles in 0.65 ms a frame, most of it the dispatches
+ * rather than the particles (`demo/dev/skinnedCloth.html?bench=1`).
+ */
+import { SkinnedCloth } from '@driftengine/physics';
+import { computeHostOf } from './backend/webgpu/computeHost.js';
+import { GpuSkinnedCloth } from './backend/webgpu/gpuSkinnedCloth.js';
+/** A garment for `renderer`, from a set-up checked by name. */
+export function createSkinnedCloth(renderer, setup) {
+    const host = computeHostOf(renderer);
+    return host === null ? new CpuCloth(renderer, setup) : new DeviceCloth(host, setup);
+}
+class DeviceCloth {
+    host;
+    runsOn = 'device';
+    particles;
+    cloth;
+    constructor(host, setup) {
+        this.host = host;
+        this.cloth = new GpuSkinnedCloth(host.device(), setup);
+        this.particles = this.cloth.particles;
+    }
+    step(globals, model, dt) {
+        if (this.host.lost())
+            return;
+        this.cloth.advance(globals, model, dt, this.host.changeFrame());
+    }
+    setWind(x, y, z) {
+        this.cloth.setWind(x, y, z);
+    }
+    reset() {
+        if (this.host.lost())
+            return;
+        this.cloth.reset();
+    }
+    /** Its buffers at once — its work is submitted — and its textures with the frame's. */
+    dispose() {
+        this.cloth.dispose();
+        this.host.retire(this.cloth.particles.textures);
+    }
+    /** The particles where the last step left them: the parity check's door, waits on the device. */
+    read() {
+        return this.cloth.read();
+    }
+}
+class CpuCloth {
+    renderer;
+    runsOn = 'cpu';
+    particles;
+    cloth;
+    /** The frame's particles at `alpha`, before they go up. */
+    staging;
+    constructor(renderer, setup) {
+        this.renderer = renderer;
+        this.cloth = new SkinnedCloth(setup);
+        this.particles = renderer.createClothParticles(this.cloth.count);
+        this.staging = new Float32Array(this.cloth.count * 3);
+    }
+    step(globals, model, dt) {
+        this.cloth.setPose(globals, model);
+        this.cloth.advance(dt);
+        this.cloth.interpolate(this.cloth.alpha, this.staging);
+        this.renderer.updateClothParticles(this.particles, this.staging);
+    }
+    setWind(x, y, z) {
+        this.cloth.setWind(x, y, z);
+    }
+    reset() {
+        this.cloth.reset();
+    }
+    dispose() {
+        this.renderer.disposeClothParticles(this.particles);
+    }
+}

package/dist/render/surfaceModel.d.ts

@@ -0,0 +1,129 @@
+/**
+ * A material's shading model: how its surface answers light, when the standard model is not what
+ * it is made of — brushed metal, hair, skin, an eye.
+ *
+ * **A frozen descriptor, made once by a factory, carrying a kind and that model's numbers.** The
+ * standard model is `null`, exactly today's shader, and a scene that never names a model compiles
+ * nothing of any of them: each is a pipeline constant of its own (`MODEL_ANISOTROPIC` and the rest
+ * in `shaders/flat/models.ts`), off in every pipeline but the ones a material asks for.
+ *
+ * **Two vectors of numbers a material, and no more.** The lit stage's eight-light build is 254 of
+ * the 256 uniform vectors an Adreno 740 offers, so a model's numbers are packed into
+ * `uModelParams[2]` — the last component of the second says whether a model map is bound — and
+ * every model fits. See `packModel` for each layout.
+ *
+ * **The eye's axis is the one number that moves.** It is the eye's forward direction in the world,
+ * which a turning head or a glance changes every frame; the lit stage has no room left for another
+ * varying (sixteen, WebGPU's ceiling), so the renderer turns the descriptor's mesh-local axis by
+ * the draw's model matrix and the eye's joint each draw, with `eyeAxisInWorld`.
+ */
+import type { Vec3 } from '../math/color.ts';
+/** Strands of brushed metal, satin or hair-like fibre: a highlight stretched across them. */
+export interface AnisotropicModel {
+    readonly kind: 'anisotropic';
+    /** 0 to 1: how far the highlight is stretched along the tangent. */
+    readonly strength: number;
+    /** Radians, turning the stretch's direction from the tangent toward the bitangent. */
+    readonly rotation: number;
+}
+/**
+ * Hair: three lobes along the strand, which is the mesh's tangent, running from root to tip
+ * (`hairLobes.ts`). A model map's green turns each strand's tilt by up to half of it either way and
+ * its blue is occlusion.
+ */
+export interface HairModel {
+    readonly kind: 'hair';
+    /**
+     * Radians the cuticle's scales tilt the strand's surface: positive moves the white highlight
+     * toward the root and the coloured one toward the tip. A card whose tangent runs tip to root
+     * takes it negative.
+     */
+    readonly shift: number;
+    /** 0 to 1: the light scattered through many strands, tinted by their colour. */
+    readonly scatter: number;
+    /** How strongly light from behind glows through: the transmitted lobe. */
+    readonly backlit: number;
+}
+/** Skin: light scattered beneath the surface, reddening its terminator and its thin parts. */
+export interface SkinModel {
+    readonly kind: 'skin';
+    /** The colour light keeps travelling beneath the surface — the mean free path, as a colour. */
+    readonly scatterColor: Vec3;
+    /** Metres: how far light travels beneath it before it leaves. */
+    readonly radius: number;
+    /** 0 to 1: how much a light behind a thin part shows through it. */
+    readonly transmission: number;
+    /** Which of up to eight profiles the screen-space scattering blurs this skin by. */
+    readonly profile: number;
+}
+/** An eye: an iris seen through a cornea, which refracts it, under a mirror-smooth highlight. */
+export interface EyeModel {
+    readonly kind: 'eye';
+    /** The iris's radius, in texture coordinates from the centre of the eye's map. */
+    readonly irisRadius: number;
+    /** Metres from the cornea down to the iris. */
+    readonly irisDepth: number;
+    /** The cornea's index of refraction. */
+    readonly ior: number;
+    /** How smooth the cornea's highlight is. */
+    readonly corneaRoughness: number;
+    /** The eye's forward direction, in the mesh's own space at its bind pose. */
+    readonly axis: Vec3;
+    /** The joint the eye turns with, or -1 for an eye placed by its model matrix alone. */
+    readonly joint: number;
+}
+/** Every model a material can name, by its `kind`: see `SurfaceMaterial.model`. */
+export type SurfaceModel = AnisotropicModel | HairModel | SkinModel | EyeModel;
+/** A model's name, which also picks its pipeline switch: `SURFACE_MODEL_SWITCH`. */
+export type SurfaceModelKind = SurfaceModel['kind'];
+/** Every kind, in the order the lit stage declares their switches. */
+export declare const SURFACE_MODEL_KINDS: readonly SurfaceModelKind[];
+/** The lit stage's switch for each kind. */
+export declare const SURFACE_MODEL_SWITCH: Readonly<Record<SurfaceModelKind, string>>;
+/** Floats a material's model takes: `uModelParams[2]`. */
+export declare const MODEL_PARAM_FLOATS = 8;
+/** Brushed metal and the like, after glTF's `KHR_materials_anisotropy`: a strength and a turn. */
+export declare function anisotropicModel(options?: {
+    strength?: number;
+    rotation?: number;
+}): AnisotropicModel;
+/** Hair, along the mesh's tangent from root to tip. A tilt of 3°, within the 2.5° to 5° measured. */
+export declare function hairModel(options?: {
+    shift?: number;
+    scatter?: number;
+    backlit?: number;
+}): HairModel;
+/** Skin. The defaults are a fair skin's: a red mean free path a little over a centimetre long. */
+export declare function skinModel(options?: {
+    scatterColor?: Vec3;
+    radius?: number;
+    transmission?: number;
+    profile?: number;
+}): SkinModel;
+/** An eye. The defaults are a human eye's, its axis along the mesh's +Z. */
+export declare function eyeModel(options?: {
+    irisRadius?: number;
+    irisDepth?: number;
+    ior?: number;
+    corneaRoughness?: number;
+    axis?: Vec3;
+    joint?: number;
+}): EyeModel;
+/**
+ * A model's numbers into `out` — eight floats, `uModelParams[0]` then `[1]` — and whether a model
+ * map is bound into the last. Zeros for the standard model. An eye's axis goes in with the
+ * descriptor's own until the draw turns it: see `eyeAxisInWorld`.
+ *
+ * - anisotropic: strength, cos and sin of the rotation · −, −, −, map
+ * - hair: shift, scatter, backlit, − · −, −, −, map
+ * - skin: the scatter colour, radius · transmission, profile, −, map
+ * - eye: iris radius, iris depth, ior, cornea roughness · the axis, map
+ */
+export declare function packModel(model: SurfaceModel | null, mapped: boolean, out: Float32Array): void;
+/**
+ * An eye's axis in the world for one draw, into `out[at…at+2]`: the descriptor's mesh-local axis
+ * turned by its joint's palette entry, where it names one and a palette is set, and then by the
+ * draw's model matrix — the turn its vertices take, without the translation. Normalised, because
+ * a palette carries a joint's scale.
+ */
+export declare function eyeAxisInWorld(model: EyeModel, placement: ArrayLike<number>, palette: ArrayLike<number> | null, out: Float32Array, at: number): void;

package/dist/render/surfaceModel.js

@@ -0,0 +1,152 @@
+/** Every kind, in the order the lit stage declares their switches. */
+export const SURFACE_MODEL_KINDS = [
+    'anisotropic',
+    'hair',
+    'skin',
+    'eye',
+];
+/** The lit stage's switch for each kind. */
+export const SURFACE_MODEL_SWITCH = {
+    anisotropic: 'MODEL_ANISOTROPIC',
+    hair: 'MODEL_HAIR',
+    skin: 'MODEL_SKIN',
+    eye: 'MODEL_EYE',
+};
+/** Floats a material's model takes: `uModelParams[2]`. */
+export const MODEL_PARAM_FLOATS = 8;
+function check(model, name, value, low, high) {
+    if (!Number.isFinite(value) || value < low || value > high) {
+        throw new Error(`${model}: ${name} must be from ${low} to ${high}, not ${String(value)}`);
+    }
+    return value;
+}
+function unit(model, name, v) {
+    const length = Math.hypot(v[0], v[1], v[2]);
+    if (!(length > 1e-6))
+        throw new Error(`${model}: ${name} must be a direction, not [${v.join(', ')}]`);
+    return [v[0] / length, v[1] / length, v[2] / length];
+}
+/** Brushed metal and the like, after glTF's `KHR_materials_anisotropy`: a strength and a turn. */
+export function anisotropicModel(options = {}) {
+    return Object.freeze({
+        kind: 'anisotropic',
+        strength: check('anisotropicModel', 'strength', options.strength ?? 1, 0, 1),
+        rotation: check('anisotropicModel', 'rotation', options.rotation ?? 0, -2 * Math.PI, 2 * Math.PI),
+    });
+}
+/** Hair, along the mesh's tangent from root to tip. A tilt of 3°, within the 2.5° to 5° measured. */
+export function hairModel(options = {}) {
+    return Object.freeze({
+        kind: 'hair',
+        shift: check('hairModel', 'shift', options.shift ?? (3 * Math.PI) / 180, -0.5, 0.5),
+        scatter: check('hairModel', 'scatter', options.scatter ?? 0.7, 0, 1),
+        backlit: check('hairModel', 'backlit', options.backlit ?? 1, 0, 4),
+    });
+}
+/** Skin. The defaults are a fair skin's: a red mean free path a little over a centimetre long. */
+export function skinModel(options = {}) {
+    const color = options.scatterColor ?? [0.85, 0.35, 0.22];
+    for (let c = 0; c < 3; c++)
+        check('skinModel', 'scatterColor', color[c], 0, 1);
+    const profile = check('skinModel', 'profile', options.profile ?? 0, 0, 7);
+    if (!Number.isInteger(profile))
+        throw new Error(`skinModel: profile must be a whole number, not ${profile}`);
+    return Object.freeze({
+        kind: 'skin',
+        scatterColor: Object.freeze([color[0], color[1], color[2]]),
+        radius: check('skinModel', 'radius', options.radius ?? 0.012, 0, 0.1),
+        transmission: check('skinModel', 'transmission', options.transmission ?? 0.5, 0, 1),
+        profile,
+    });
+}
+/** An eye. The defaults are a human eye's, its axis along the mesh's +Z. */
+export function eyeModel(options = {}) {
+    const joint = options.joint ?? -1;
+    if (!Number.isInteger(joint) || joint < -1) {
+        throw new Error(`eyeModel: joint must be a joint index or -1, not ${String(joint)}`);
+    }
+    return Object.freeze({
+        kind: 'eye',
+        irisRadius: check('eyeModel', 'irisRadius', options.irisRadius ?? 0.15, 0.001, 0.5),
+        irisDepth: check('eyeModel', 'irisDepth', options.irisDepth ?? 0.003, 0, 0.02),
+        ior: check('eyeModel', 'ior', options.ior ?? 1.336, 1, 2),
+        corneaRoughness: check('eyeModel', 'corneaRoughness', options.corneaRoughness ?? 0.02, 0, 1),
+        axis: Object.freeze(unit('eyeModel', 'axis', options.axis ?? [0, 0, 1])),
+        joint,
+    });
+}
+/**
+ * A model's numbers into `out` — eight floats, `uModelParams[0]` then `[1]` — and whether a model
+ * map is bound into the last. Zeros for the standard model. An eye's axis goes in with the
+ * descriptor's own until the draw turns it: see `eyeAxisInWorld`.
+ *
+ * - anisotropic: strength, cos and sin of the rotation · −, −, −, map
+ * - hair: shift, scatter, backlit, − · −, −, −, map
+ * - skin: the scatter colour, radius · transmission, profile, −, map
+ * - eye: iris radius, iris depth, ior, cornea roughness · the axis, map
+ */
+export function packModel(model, mapped, out) {
+    out.fill(0);
+    if (model === null)
+        return;
+    out[7] = mapped ? 1 : 0;
+    switch (model.kind) {
+        case 'anisotropic':
+            out[0] = model.strength;
+            out[1] = Math.cos(model.rotation);
+            out[2] = Math.sin(model.rotation);
+            return;
+        case 'hair':
+            out[0] = model.shift;
+            out[1] = model.scatter;
+            out[2] = model.backlit;
+            return;
+        case 'skin':
+            out[0] = model.scatterColor[0];
+            out[1] = model.scatterColor[1];
+            out[2] = model.scatterColor[2];
+            out[3] = model.radius;
+            out[4] = model.transmission;
+            out[5] = model.profile;
+            return;
+        case 'eye':
+            out[0] = model.irisRadius;
+            out[1] = model.irisDepth;
+            out[2] = model.ior;
+            out[3] = model.corneaRoughness;
+            out[4] = model.axis[0];
+            out[5] = model.axis[1];
+            out[6] = model.axis[2];
+            return;
+    }
+}
+/**
+ * An eye's axis in the world for one draw, into `out[at…at+2]`: the descriptor's mesh-local axis
+ * turned by its joint's palette entry, where it names one and a palette is set, and then by the
+ * draw's model matrix — the turn its vertices take, without the translation. Normalised, because
+ * a palette carries a joint's scale.
+ */
+export function eyeAxisInWorld(model, placement, palette, out, at) {
+    let [x, y, z] = model.axis;
+    const j = model.joint * 16;
+    if (palette !== null && model.joint >= 0 && j + 16 <= palette.length) {
+        const px = palette[j] * x + palette[j + 4] * y + palette[j + 8] * z;
+        const py = palette[j + 1] * x +
+            palette[j + 5] * y +
+            palette[j + 9] * z;
+        const pz = palette[j + 2] * x +
+            palette[j + 6] * y +
+            palette[j + 10] * z;
+        x = px;
+        y = py;
+        z = pz;
+    }
+    const m = placement;
+    const wx = m[0] * x + m[4] * y + m[8] * z;
+    const wy = m[1] * x + m[5] * y + m[9] * z;
+    const wz = m[2] * x + m[6] * y + m[10] * z;
+    const length = Math.hypot(wx, wy, wz) || 1;
+    out[at] = wx / length;
+    out[at + 1] = wy / length;
+    out[at + 2] = wz / length;
+}

package/dist/render/surfaceTexture.d.ts

@@ -1,4 +1,17 @@
+/**
+ * A GPU image the caller supplies, sampled by the flat shader as surface colour — or several, as
+ * the layers of one array.
+ *
+ * **Every surface texture is an array; a plain image is an array of one.** The lit pass has three of
+ * WebGL2's guaranteed sixteen texture units free, so a second set of array samplers beside the 2D
+ * ones was never affordable. Making the one set of samplers arrays costs no unit, and a one-layer
+ * array samples exactly as a 2D texture does. A mesh names its layer per vertex (`MeshData.layers`),
+ * so a merged block wearing forty facades is one draw.
+ */
+import type { SurfaceModel } from './surfaceModel.ts';
+import type { CompressedTextureFormat, SurfaceSource } from './compressedSource.ts';
 import type { SurfaceLayerEffect } from './surfaceEffects.ts';
+import type { CutoutMode } from './cutoutDither.ts';
 /**
  * How a texture behaves past its edges and between its texels.
  *
@@ -68,8 +81,20 @@ export interface SurfaceMaterial<Texture = SurfaceTexture> {
      */
     uOffset?: number;
     vOffset?: number;
-    /** Alpha below which a fragment is discarded. See `uAlbedoCutout`. */
+    /** Alpha below which a fragment is discarded. See `uCutout`. */
     cutout?: number;
+    /**
+     * How the cutout's edge is drawn: `'hard'`, the default and every cutout before 4.8.4, or
+     * `'dithered'`, which keeps a pixel by the share of it the texture covers so a strand of hair, a
+     * lash or a fringe of leaves has a soft edge instead of a stair of pixels.
+     *
+     * **The frame decides how a dithered edge is resolved**, because the material cannot know: under a
+     * temporal resolve (TAA or DriftTR) the pattern moves every frame and the resolve averages it;
+     * multisampled, the share goes to the GPU as alpha-to-coverage; with neither, the test is hard,
+     * since a dither nothing averages is grain. A translucent draw tests hard whatever this says. See
+     * `cutoutDither.ts`.
+     */
+    cutoutMode?: CutoutMode;
     /**
      * Whether both faces are seen: glTF's `doubleSided`, what a curtain or a leaf card is. Drawn
      * without culling, and a back face is lit as its front, with the normal turned to the viewer.
@@ -110,6 +135,19 @@ export interface SurfaceMaterial<Texture = SurfaceTexture> {
      * consumer who wants a bound map twice as bright asks here rather than rebuilding the mesh.
      */
     emissiveScale?: readonly [number, number, number];
+    /**
+     * How the surface answers light, when the standard model is not what it is made of: brushed
+     * metal, hair, skin, an eye — `anisotropicModel`, `hairModel`, `skinModel`, `eyeModel`. Null or
+     * absent is the standard model, exactly as before. **A pipeline of its own**, compiled the first
+     * time a draw asks, so a scene that names no model pays for none. See `surfaceModel.ts`.
+     */
+    model?: SurfaceModel | null;
+    /**
+     * The model's own channels, in the albedo's coordinates and layers; what each channel means is
+     * the model's to say. Absent, each model takes its own neutral. Sampled linear, like any map
+     * that is not a colour.
+     */
+    modelMap?: Texture | null;
 }
 export interface SurfaceTextureOptions {
     /**
@@ -204,12 +242,14 @@ export declare class SurfaceTexture {
     readonly layers: number;
     /** The per-layer effects table, or null for a texture given none. See `surfaceEffects.ts`. */
     private effectsTable;
+    /** The block format a compressed texture holds, or null for one uploaded from images. */
+    private readonly blockFormat;
     /**
      * One image, or an array of images that must share one size (`layerSize` refuses otherwise).
-     * Uploaded unflipped either way; see the constructor body for why.
+     * Uploaded unflipped either way; see the constructor body for why. Or blocks, uploaded as they are
+     * where `compressed` — the formats this context samples — has theirs; see `compressedSource.ts`.
      */
-    constructor(gl: WebGL2RenderingContext, source: TexImageSource | readonly TexImageSource[], options?: SurfaceTextureOptions);
-    /** Bind the effects table to `unit`, or `fallback` for a texture given none. */
+    constructor(gl: WebGL2RenderingContext, source: SurfaceSource | readonly SurfaceSource[], options?: SurfaceTextureOptions, compressed?: readonly CompressedTextureFormat[]);
     /** Whether this texture carries an effects table, which the lit program reads only once one exists. */
     get hasEffects(): boolean;
     bindEffects(gl: WebGL2RenderingContext, unit: number, fallback: WebGLTexture): void;