@driftengine/core 4.10.0 → 4.11.1

package/dist/render/skinnedClothRun.js

@@ -11,74 +11,142 @@
  * 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`).
+ *
+ * **Several garments step as one with `createSkinnedClothSet`**: one pass, one submit and one
+ * garment's dispatches a step for all of them, where a garment each was a pass, a submit and its
+ * own dispatches each. They must share a step, substeps, iterations and most steps a frame.
  */
 import { SkinnedCloth } from '@driftengine/physics';
 import { computeHostOf } from './backend/webgpu/computeHost.js';
-import { GpuSkinnedCloth } from './backend/webgpu/gpuSkinnedCloth.js';
+import { GpuClothSet } from './backend/webgpu/gpuClothSet.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);
+    const set = host === null ? new CpuClothSet(renderer, [setup]) : new DeviceClothSet(host, [setup]);
+    return new OneGarment(set);
+}
+/** A set of one, as a solver: what `createSkinnedCloth` hands back. */
+class OneGarment {
+    set;
+    particles;
+    runsOn;
+    constructor(set) {
+        this.set = set;
+        this.particles = set.particles[0];
+        this.runsOn = set.runsOn;
+    }
+    step(globals, model, dt) {
+        this.set.setPose(0, globals, model);
+        this.set.step(dt);
+    }
+    setWind(x, y, z) {
+        this.set.setWind(0, x, y, z);
+    }
+    reset() {
+        this.set.reset(0);
+    }
+    dispose() {
+        this.set.dispose();
+    }
+    /** The particles where the last step left them: the parity check's door. */
+    read() {
+        return this.set.read(0);
+    }
 }
-class DeviceCloth {
+/**
+ * Garments for `renderer` stepped together, from set-ups checked by name: one pass, one submit and
+ * one garment's dispatches a step on the device, whatever the count. They must agree on `step`,
+ * `substeps`, `iterations` and `maxSteps`, and are refused by the first they disagree on.
+ */
+export function createSkinnedClothSet(renderer, setups) {
+    const host = computeHostOf(renderer);
+    return host === null ? new CpuClothSet(renderer, setups) : new DeviceClothSet(host, setups);
+}
+class DeviceClothSet {
     host;
     runsOn = 'device';
     particles;
-    cloth;
-    constructor(host, setup) {
+    set;
+    constructor(host, setups) {
         this.host = host;
-        this.cloth = new GpuSkinnedCloth(host.device(), setup);
-        this.particles = this.cloth.particles;
+        this.set = new GpuClothSet(host.device(), setups);
+        const particles = [];
+        for (let g = 0; g < this.set.size; g++)
+            particles.push(this.set.particles(g));
+        this.particles = particles;
     }
-    step(globals, model, dt) {
+    setPose(g, globals, model) {
         if (this.host.lost())
             return;
-        this.cloth.advance(globals, model, dt, this.host.changeFrame());
+        this.set.setPose(g, globals, model);
     }
-    setWind(x, y, z) {
-        this.cloth.setWind(x, y, z);
+    setWind(g, x, y, z) {
+        this.set.setWind(g, x, y, z);
     }
-    reset() {
+    reset(g) {
+        if (this.host.lost())
+            return;
+        this.set.reset(g);
+    }
+    step(dt) {
         if (this.host.lost())
             return;
-        this.cloth.reset();
+        this.set.step(dt, this.host.changeFrame());
     }
     /** 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);
+        this.set.dispose();
+        for (let g = 0; g < this.set.size; g++)
+            this.host.retire(this.set.particles(g).textures);
     }
-    /** The particles where the last step left them: the parity check's door, waits on the device. */
-    read() {
-        return this.cloth.read();
+    /** Garment `g`'s particles where its last step left them: the parity check's, waits on the device. */
+    read(g) {
+        return this.set.read(g);
     }
 }
-class CpuCloth {
+class CpuClothSet {
     renderer;
     runsOn = 'cpu';
     particles;
-    cloth;
-    /** The frame's particles at `alpha`, before they go up. */
+    cloths;
+    /** Each garment's particles at `alpha`, before they go up. */
     staging;
-    constructor(renderer, setup) {
+    constructor(renderer, setups) {
         this.renderer = renderer;
-        this.cloth = new SkinnedCloth(setup);
-        this.particles = renderer.createClothParticles(this.cloth.count);
-        this.staging = new Float32Array(this.cloth.count * 3);
+        this.cloths = setups.map((setup) => new SkinnedCloth(setup));
+        this.particles = this.cloths.map((cloth) => renderer.createClothParticles(cloth.count));
+        this.staging = this.cloths.map((cloth) => new Float32Array(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);
+    setPose(g, globals, model) {
+        this.at(g).setPose(globals, model);
     }
-    setWind(x, y, z) {
-        this.cloth.setWind(x, y, z);
+    setWind(g, x, y, z) {
+        this.at(g).setWind(x, y, z);
     }
-    reset() {
-        this.cloth.reset();
+    reset(g) {
+        this.at(g).reset();
+    }
+    step(dt) {
+        for (let g = 0; g < this.cloths.length; g++) {
+            const cloth = this.cloths[g];
+            const staging = this.staging[g];
+            cloth.advance(dt);
+            cloth.interpolate(cloth.alpha, staging);
+            this.renderer.updateClothParticles(this.particles[g], staging);
+        }
     }
     dispose() {
-        this.renderer.disposeClothParticles(this.particles);
+        for (const particles of this.particles)
+            this.renderer.disposeClothParticles(particles);
+    }
+    /** Garment `g`'s particles where its last step left them, as the device set reads its own. */
+    read(g) {
+        return Promise.resolve(new Float32Array(this.at(g).positions));
+    }
+    at(g) {
+        const cloth = this.cloths[g];
+        if (cloth === undefined)
+            throw new Error(`skinned cloth set: no garment ${g}`);
+        return cloth;
     }
 }

package/dist/render/surfaceLayers.d.ts

@@ -0,0 +1,107 @@
+/**
+ * A material blended from layers by a mask: `SurfaceMaterial.layers`, the four vectors
+ * `shaders/flat/layered.ts` reads it from, and the decisions both backends take about it.
+ */
+import type { SurfaceProjection } from './surfaceProjection.ts';
+/** The most layers a material blends: a base and one for each of the mask's four channels. */
+export declare const MAX_SURFACE_LAYERS = 5;
+/**
+ * Up to five layers, each its own colour, normal and roughness at its own repeat, blended by a mask.
+ *
+ * **Layer `i` is layer `i` of the material's arrays**: `albedo`, `normal` and `orm` each an array
+ * whose layers are the material's layers in order, read at the mesh's coordinates times
+ * `repeats[i]`, so rock can repeat forty times across a cliff while the moss on it repeats three.
+ * Where the material has a `projection`, the layers are read at the world's horizontal position
+ * instead, so a repeat is so many a metre (with the projection's own scale at 1). **The mask** is
+ * read at the mesh's own coordinates and lays each layer over those before it: red lays layer 1
+ * over the base, green layer 2 over that, blue layer 3, alpha layer 4. `emissiveLayer` gives the
+ * material's emissive map to one layer, glowing where that layer shows and nowhere it is covered;
+ * absent, the map glows as on any material.
+ *
+ * **Maps beyond the layers ride the material's own arrays, after its layers**, so they take no
+ * texture binding of their own — the lit stage has none to spare: a mask the ORM array carries
+ * (`mask: 'orm'`) is the ORM array's layer just past the layers, an `addMask` the one after that,
+ * and `meshNormal` the normal array's layer just past the layers. Each shares its array's size and
+ * format, so a four-channel mask wants an array that stores four.
+ *
+ * **What it gives up**: every layer's maps are read wherever any shows, three reads a layer, so five
+ * layers are fifteen reads where one material is three; layers share an array's size and format; a
+ * cutout reads the base layer's alpha; a mask read where a model's map goes leaves no room for one,
+ * so a lightmapped surface carries its mask in its ORM array or its vertices; a triplanar projection
+ * lays layers on the horizontal plane alone; and a mask is sampled linear, so it is uploaded as data
+ * (`colorSpace: 'linear'`).
+ */
+export interface SurfaceLayers<Texture> {
+    /**
+     * Where the weights come from, red to alpha laying layers 1 to 4: a map read where a shading
+     * model's map goes; `'orm'`, the ORM array's layer just past the layers; or `'vertex'`, the
+     * vertex colour's red, green and blue, which then weights the layers instead of tinting them.
+     */
+    readonly mask: Texture | 'orm' | 'vertex';
+    /** Each layer's repeats across the mesh's coordinates, base first: one to five of them. */
+    readonly repeats: readonly number[];
+    /** The layer the emissive map glows on, 0 to 4. Absent: everywhere, as on any material. */
+    readonly emissiveLayer?: number;
+    /**
+     * How the layers combine. `'over'`, the default, lays each over the ones before it by its
+     * channel. `'sum'` mixes the base toward the sum of each layer times its channel, by the channels'
+     * sum held to 1: two layers at half each are both half there, where laying over would let the
+     * second cover half of the first.
+     */
+    readonly blend?: 'over' | 'sum';
+    /**
+     * A second mask added to one layer's weight, read where the layers are (the world, under a
+     * `projection`) times `repeat`, its red times `intensity`: sand drifting into the gravel's layer at
+     * a scale of its own. The ORM array's layer after the layers and any mask it carries.
+     */
+    readonly addMask?: {
+        readonly layer: number;
+        readonly repeat: number;
+        readonly intensity: number;
+    };
+    /**
+     * One layer weighted by how much the surface faces up rather than by its mask channel:
+     * `saturate(bias + sharpness × (up / 2 + 1/2))`, `up` the world normal's upward share before any
+     * normal map. Snow on the tops of rocks, moss on a ledge.
+     */
+    readonly facing?: {
+        readonly layer: number;
+        readonly bias: number;
+        readonly sharpness: number;
+    };
+    /**
+     * A normal map read at the mesh's own coordinates and tangents, the normal array's layer just past
+     * the layers, under the layers' blended normal: the large shapes of a rock or a cliff, which a
+     * layer repeating forty times across it cannot carry.
+     */
+    readonly meshNormal?: boolean;
+}
+/** Floats `packSurfaceLayers` writes: four vectors. */
+export declare const LAYER_FLOATS = 16;
+/**
+ * `layers` into `out`, four vectors. The first five floats are the repeats (1 for a layer not
+ * given), then how many layers there are, which one glows (−1 for none) and where the mask comes
+ * from (0 a map, 1 the ORM array, 2 the vertex colour). Then the blend (0 over, 1 sum), whether a
+ * mesh normal is laid under the layers, the added mask's layer (−1 for none) and repeat; its
+ * intensity; and the facing layer (−1 for none), its bias and its sharpness. Zeros, no layers, where
+ * there are none.
+ *
+ * A repeat that is not a positive number is 1, so a layer is never laid at a scale that collapses it
+ * to a point; a glow, an added mask or a facing layer naming a layer there is not is none, and the
+ * base, which no channel lays, is not one an added mask or the facing can name.
+ */
+export declare function packSurfaceLayers<Texture>(layers: SurfaceLayers<Texture> | null | undefined, out: Float32Array): void;
+/** The texture a layered material's mask is, where it is one rather than another array or the vertices. */
+export declare function layerMaskMap<Texture>(layers: SurfaceLayers<Texture> | null | undefined): Texture | null;
+/**
+ * Whether a material's layers can be drawn beside its `modelMap`: always, unless the mask is a map,
+ * which is read where a model's map goes and so cannot share the slot with one — a lightmap's page
+ * among them. The backends draw such a material as one layer and say so once.
+ */
+export declare function layersFitBeside<Texture>(layers: SurfaceLayers<Texture>, modelMap: Texture | null | undefined): boolean;
+/**
+ * The projection a layered material is drawn with: a triplanar one is laid on the horizontal plane,
+ * at its own scale, since every layer's maps read three times over would be forty-five reads a pixel.
+ * Anything else as it was. Whether to say so is the caller's.
+ */
+export declare function layeredProjection<Texture>(projection: SurfaceProjection | null | undefined, layers: SurfaceLayers<Texture> | null | undefined): SurfaceProjection | null;

package/dist/render/surfaceLayers.js

@@ -0,0 +1,82 @@
+/** The most layers a material blends: a base and one for each of the mask's four channels. */
+export const MAX_SURFACE_LAYERS = 5;
+/** Floats `packSurfaceLayers` writes: four vectors. */
+export const LAYER_FLOATS = 16;
+/** Where the mask is read, as the fourth float of the second vector carries it. */
+const MASK_SOURCE = { map: 0, orm: 1, vertex: 2 };
+/**
+ * `layers` into `out`, four vectors. The first five floats are the repeats (1 for a layer not
+ * given), then how many layers there are, which one glows (−1 for none) and where the mask comes
+ * from (0 a map, 1 the ORM array, 2 the vertex colour). Then the blend (0 over, 1 sum), whether a
+ * mesh normal is laid under the layers, the added mask's layer (−1 for none) and repeat; its
+ * intensity; and the facing layer (−1 for none), its bias and its sharpness. Zeros, no layers, where
+ * there are none.
+ *
+ * A repeat that is not a positive number is 1, so a layer is never laid at a scale that collapses it
+ * to a point; a glow, an added mask or a facing layer naming a layer there is not is none, and the
+ * base, which no channel lays, is not one an added mask or the facing can name.
+ */
+export function packSurfaceLayers(layers, out) {
+    out.fill(0);
+    if (layers === null || layers === undefined || layers.repeats.length === 0)
+        return;
+    const count = Math.min(layers.repeats.length, MAX_SURFACE_LAYERS);
+    for (let i = 0; i < MAX_SURFACE_LAYERS; i++)
+        out[i] = positive(i < count ? layers.repeats[i] : 1);
+    out[5] = count;
+    const glow = layers.emissiveLayer;
+    out[6] = glow !== undefined && Number.isInteger(glow) && glow >= 0 && glow < count ? glow : -1;
+    out[7] =
+        layers.mask === 'orm'
+            ? MASK_SOURCE.orm
+            : layers.mask === 'vertex'
+                ? MASK_SOURCE.vertex
+                : MASK_SOURCE.map;
+    out[8] = layers.blend === 'sum' ? 1 : 0;
+    out[9] = layers.meshNormal === true ? 1 : 0;
+    const added = layers.addMask;
+    const addLayer = laidLayer(added?.layer, count);
+    out[10] = addLayer;
+    out[11] = addLayer < 0 ? 0 : positive(added?.repeat);
+    out[12] = addLayer < 0 ? 0 : finite(added?.intensity);
+    const facing = layers.facing;
+    const faceLayer = laidLayer(facing?.layer, count);
+    out[13] = faceLayer;
+    out[14] = faceLayer < 0 ? 0 : finite(facing?.bias);
+    out[15] = faceLayer < 0 ? 0 : finite(facing?.sharpness);
+}
+/** The texture a layered material's mask is, where it is one rather than another array or the vertices. */
+export function layerMaskMap(layers) {
+    const mask = layers?.mask;
+    return mask === undefined || mask === 'orm' || mask === 'vertex' ? null : mask;
+}
+/**
+ * Whether a material's layers can be drawn beside its `modelMap`: always, unless the mask is a map,
+ * which is read where a model's map goes and so cannot share the slot with one — a lightmap's page
+ * among them. The backends draw such a material as one layer and say so once.
+ */
+export function layersFitBeside(layers, modelMap) {
+    return modelMap === null || modelMap === undefined || layerMaskMap(layers) === null;
+}
+/**
+ * The projection a layered material is drawn with: a triplanar one is laid on the horizontal plane,
+ * at its own scale, since every layer's maps read three times over would be forty-five reads a pixel.
+ * Anything else as it was. Whether to say so is the caller's.
+ */
+export function layeredProjection(projection, layers) {
+    if (projection === null || projection === undefined)
+        return null;
+    if (layers === null || layers === undefined || projection.kind !== 'triplanar')
+        return projection;
+    return { kind: 'planar', scale: projection.scale };
+}
+/** A layer an added mask or the facing may name: one a channel lays, 1 to `count − 1`, or −1. */
+function laidLayer(layer, count) {
+    return layer !== undefined && Number.isInteger(layer) && layer >= 1 && layer < count ? layer : -1;
+}
+function positive(value) {
+    return value !== undefined && Number.isFinite(value) && value > 0 ? value : 1;
+}
+function finite(value) {
+    return value !== undefined && Number.isFinite(value) ? value : 0;
+}

package/dist/render/surfaceOverlay.d.ts

@@ -27,12 +27,24 @@ export interface OverlayRegion {
  * raised to a contrast, times a noise laid in screen space, a slow pulse and a mask, in a colour.
  * Added to what the surface emits, and not gated on the night as emission is: it is a glow the
  * surface wears, not light it gives off.
+ *
+ * **Or, with `mode: 'blend'`, a colour the surface is pulled toward**, lit like the rest of it: the
+ * base colour mixed toward the rim's by the edge times `alpha`, before any light reads it, so the
+ * rim is bright where light falls and dark where none does. The colour is `colour` times
+ * `intensity`, each channel held at 1 as a base colour is, so a colour of 8 red is a red of 1 and
+ * not a glow; `alpha` is the weight, which may pass 1 to saturate the edge sooner.
  */
 export interface SurfaceRim {
     readonly colour: Vec3;
-    /** How bright, 0 for none. Multiplied with `alpha`. */
+    /**
+     * How bright, 0 for none, multiplied with `alpha`. Where the rim blends it scales `colour`
+     * instead, so 0 there is a rim of black, and `alpha` alone says how much: 0 for none.
+     */
     readonly intensity: number;
+    /** The rim's weight, 1 unless given. */
     readonly alpha?: number;
+    /** `'add'`, the default, lays the rim on as glow; `'blend'` pulls the base colour toward it, lit. */
+    readonly mode?: 'add' | 'blend';
     /** The edge's exponent: larger keeps the rim nearer the silhouette. 1.5 unless given. */
     readonly falloff?: number;
     /**
@@ -118,10 +130,11 @@ export declare const OVERLAY_FLOATS: number;
  * no overlay. A region with a zero scale is an image not given, and its term reads as none — a
  * noise of 1, a mask of 0, no wrinkle — and every region is one without `maps`. Fifteen vectors:
  *
- * - 0: rim colour, rim strength (intensity times alpha; 0 is no rim)
+ * - 0: rim colour, rim strength (intensity times alpha; 0 is no rim). A blending rim: the colour
+ *   times intensity, each channel held at 1, and the alpha alone
  * - 1: falloff, upward lean, contrast, mask weight
  * - 2: the rim's noise region; 3: its scroll along x and y, its tiling, the pulse's rate
- * - 4: the pulse's low and high (1 and 1 where none)
+ * - 4: the pulse's low and high (1 and 1 where none), and the mode: 0 adds, 1 blends
  * - 5: the rim's mask region
  * - 6: the dissolve's noise region (a zero scale is no dissolve); 7: its tiling, threshold, edge
  * - 8: the edge's light and its strength; 9: the laid-over colour and its amount

package/dist/render/surfaceOverlay.js

@@ -14,10 +14,11 @@ function region(out, at, r) {
  * no overlay. A region with a zero scale is an image not given, and its term reads as none — a
  * noise of 1, a mask of 0, no wrinkle — and every region is one without `maps`. Fifteen vectors:
  *
- * - 0: rim colour, rim strength (intensity times alpha; 0 is no rim)
+ * - 0: rim colour, rim strength (intensity times alpha; 0 is no rim). A blending rim: the colour
+ *   times intensity, each channel held at 1, and the alpha alone
  * - 1: falloff, upward lean, contrast, mask weight
  * - 2: the rim's noise region; 3: its scroll along x and y, its tiling, the pulse's rate
- * - 4: the pulse's low and high (1 and 1 where none)
+ * - 4: the pulse's low and high (1 and 1 where none), and the mode: 0 adds, 1 blends
  * - 5: the rim's mask region
  * - 6: the dissolve's noise region (a zero scale is no dissolve); 7: its tiling, threshold, edge
  * - 8: the edge's light and its strength; 9: the laid-over colour and its amount
@@ -31,10 +32,14 @@ export function packSurfaceOverlay(overlay, out) {
     const images = overlay.maps !== undefined;
     const rim = overlay.rim;
     if (rim !== undefined) {
-        out[0] = finite(rim.colour[0], 0);
-        out[1] = finite(rim.colour[1], 0);
-        out[2] = finite(rim.colour[2], 0);
-        out[3] = Math.max(0, finite(rim.intensity, 0) * finite(rim.alpha, 1));
+        const blend = rim.mode === 'blend';
+        const scale = blend ? finite(rim.intensity, 0) : 1;
+        for (let c = 0; c < 3; c++) {
+            const channel = finite(rim.colour[c], 0) * scale;
+            out[c] = blend ? Math.min(Math.max(channel, 0), 1) : channel;
+        }
+        out[3] = Math.max(0, (blend ? 1 : finite(rim.intensity, 0)) * finite(rim.alpha, 1));
+        out[18] = blend ? 1 : 0;
         out[4] = Math.max(0, finite(rim.falloff, 1.5));
         out[5] = Math.max(0, finite(rim.upward, 0.4));
         out[6] = Math.max(0, finite(rim.contrast, 1));

package/dist/render/surfaceProjection.d.ts

@@ -0,0 +1,34 @@
+/**
+ * A material's maps placed by where a point is in the world: `SurfaceMaterial.projection`, and the
+ * one vector `shaders/flat/worldUv.ts` reads it from.
+ */
+/**
+ * Texture coordinates from the world rather than from the mesh.
+ *
+ * **`'planar'`** lays the maps across the two horizontal axes, `x` and `z`: ground whose mesh
+ * carries flat coordinates, or none worth reading, shows its texture at `scale` repeats a metre.
+ * **`'triplanar'`** reads each map on the three planes across `x`, `y` and `z` and blends them by
+ * how squarely the surface faces each, the normal's components raised to `sharpness`, so walls and
+ * rock wear a texture without stretching. See `worldUv.ts` for the normal map's blend.
+ *
+ * **What it gives up**: the world's coordinates do not move with a mesh, so a moving mesh slides
+ * under its texture; triplanar reads every map three times; and the material's `uScale`, `vScale`
+ * and offsets, which are the mesh's coordinates', do not apply.
+ */
+export interface SurfaceProjection {
+    readonly kind: 'planar' | 'triplanar';
+    /** Repeats a metre: 2 lays a texture every half metre. */
+    readonly scale: number;
+    /** How sharply triplanar's planes meet: the exponent on the normal. 4 unless given. */
+    readonly sharpness?: number;
+}
+/** Floats `packSurfaceProjection` writes: one vector. */
+export declare const PROJECTION_FLOATS = 4;
+/**
+ * `projection` into `out`: its kind (0 none, 1 planar, 2 triplanar), its repeats a metre and its
+ * sharpness; zeros for none. A scale that is not finite and above zero projects nothing, so a
+ * material is never drawn at a scale that collapses its texture to a point.
+ */
+export declare function packSurfaceProjection(projection: SurfaceProjection | null | undefined, out: Float32Array): void;
+/** Whether a material projects its maps at all. */
+export declare function projects(projection: SurfaceProjection | null | undefined): boolean;

package/dist/render/surfaceProjection.js

@@ -0,0 +1,30 @@
+/**
+ * A material's maps placed by where a point is in the world: `SurfaceMaterial.projection`, and the
+ * one vector `shaders/flat/worldUv.ts` reads it from.
+ */
+/** Floats `packSurfaceProjection` writes: one vector. */
+export const PROJECTION_FLOATS = 4;
+/**
+ * `projection` into `out`: its kind (0 none, 1 planar, 2 triplanar), its repeats a metre and its
+ * sharpness; zeros for none. A scale that is not finite and above zero projects nothing, so a
+ * material is never drawn at a scale that collapses its texture to a point.
+ */
+export function packSurfaceProjection(projection, out) {
+    out.fill(0);
+    if (projection === null || projection === undefined)
+        return;
+    const scale = projection.scale;
+    if (!Number.isFinite(scale) || scale <= 0)
+        return;
+    out[0] = projection.kind === 'triplanar' ? 2 : 1;
+    out[1] = scale;
+    const sharpness = projection.sharpness ?? 4;
+    out[2] = Number.isFinite(sharpness) ? Math.min(Math.max(sharpness, 1), 64) : 4;
+}
+/** Whether a material projects its maps at all. */
+export function projects(projection) {
+    return (projection !== null &&
+        projection !== undefined &&
+        Number.isFinite(projection.scale) &&
+        projection.scale > 0);
+}

package/dist/render/surfaceTexture.d.ts

@@ -8,6 +8,8 @@
  * 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 { SurfaceLayers } from './surfaceLayers.ts';
+import type { SurfaceProjection } from './surfaceProjection.ts';
 import type { SurfaceModel } from './surfaceModel.ts';
 import type { CompressedTextureFormat, CompressedTextureSource, SurfaceSource } from './compressedSource.ts';
 import type { SurfaceLayerEffect } from './surfaceEffects.ts';
@@ -196,6 +198,43 @@ export interface SurfaceMaterial<Texture = SurfaceTexture> {
      * and an 8-bit frame clips the brighter peak without `hdrScene`.
      */
     physicalSpecular?: boolean;
+    /**
+     * Texture coordinates from where a point is in the world rather than from the mesh: `'planar'`
+     * across the horizontal axes for ground, `'triplanar'` on three planes for walls and rock, at so
+     * many repeats a metre. Absent, the mesh's, as every material's were. **A lit switch**, compiled in
+     * the first time a material asks, so a scene that never asks pays nothing. See
+     * `surfaceProjection.ts` for what it gives up.
+     */
+    projection?: SurfaceProjection | null;
+    /**
+     * How much light from behind a thin surface lets through, 0 to 1: a banner lit from behind, a
+     * leaf against the sun, a lampshade. The light falling on the far side — the sun, lamps, area
+     * lights, DriftLight — reaches the eye through the surface, coloured by its own colour; a metal
+     * lets none through. 0, the default, is every material as it was. Two-sided or not: a one-sided
+     * surface seen from its front shows the light behind it as well.
+     *
+     * **What it gives up**: a thin surface, not a volume, so a thick one lets through as much as a
+     * sheet; the light behind is not blurred by the surface; and none of it on glass, which lets
+     * light through by its own rule (`TranslucentMeshOptions.glass`).
+     */
+    diffuseTransmission?: number;
+    /**
+     * The colour the light from behind takes through the surface, linear, in place of its own colour:
+     * a banner whose cloth glows a flat red behind a printed face, a leaf whose veins are not what the
+     * light through it shows. Absent, the surface's colour, as `diffuseTransmission` has always used.
+     * Each component is held at zero or above. Read only where `diffuseTransmission` lets light through.
+     */
+    transmissionColor?: readonly [number, number, number] | null;
+    /**
+     * Up to five layers blended by a mask, each at its own repeat: `albedo`, `normal` and `orm` arrays
+     * whose layers are the material's, and a mask laying each over the ones before it or summing them,
+     * from a map, the ORM array or the vertex colour; under a `projection` the layers are placed by the
+     * world. Absent, the material is one layer, as every material was. **A lit switch**, compiled in the
+     * first time a material asks. A mask that is a map is read where `modelMap` goes, so such a
+     * material carries one or the other; a lightmapped one keeps its mask in its ORM array or its
+     * vertices. See `surfaceLayers.ts` for the rest and what it gives up.
+     */
+    layers?: SurfaceLayers<Texture> | null;
 }
 export interface SurfaceTextureOptions {
     /**

package/dist/render/transmission.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A thin surface's light from behind as the lit stage reads it: `SurfaceMaterial.diffuseTransmission`
+ * and `transmissionColor` into the four lanes of the glass tint an opaque material leaves unused.
+ *
+ * **The colour rides lanes glass owns**, because the lit stage's uniform rows are spent
+ * (`flat/preamble.ts`): a pane writes its own tint there for its draw, so whatever binds a pane
+ * puts this back after it, or the next draw of the material lets light through in the pane's colour.
+ * **−1 in the colour lanes means "the albedo"**, which is what a material naming no colour has
+ * always let through, so a scene that names none draws to the bit as it did.
+ */
+/** What a material lets through from behind and in which colour, as the glass tint carries it. */
+export interface Transmission {
+    readonly diffuseTransmission?: number;
+    readonly transmissionColor?: readonly [number, number, number] | null;
+}
+/**
+ * `material` into `out`: the colour, or −1 three times where it names none, then the amount held
+ * to 0..1. A colour component below zero is held at zero, so a mistyped colour lets no light
+ * through rather than reading as "the albedo".
+ */
+export declare function resolveTransmission(material: Transmission | null, out: Float32Array): void;

package/dist/render/transmission.js

@@ -0,0 +1,21 @@
+/**
+ * A thin surface's light from behind as the lit stage reads it: `SurfaceMaterial.diffuseTransmission`
+ * and `transmissionColor` into the four lanes of the glass tint an opaque material leaves unused.
+ *
+ * **The colour rides lanes glass owns**, because the lit stage's uniform rows are spent
+ * (`flat/preamble.ts`): a pane writes its own tint there for its draw, so whatever binds a pane
+ * puts this back after it, or the next draw of the material lets light through in the pane's colour.
+ * **−1 in the colour lanes means "the albedo"**, which is what a material naming no colour has
+ * always let through, so a scene that names none draws to the bit as it did.
+ */
+/**
+ * `material` into `out`: the colour, or −1 three times where it names none, then the amount held
+ * to 0..1. A colour component below zero is held at zero, so a mistyped colour lets no light
+ * through rather than reading as "the albedo".
+ */
+export function resolveTransmission(material, out) {
+    const colour = material?.transmissionColor ?? null;
+    for (let i = 0; i < 3; i++)
+        out[i] = colour === null ? -1 : Math.max(colour[i] ?? 0, 0) || 0;
+    out[3] = Math.min(Math.max(material?.diffuseTransmission ?? 0, 0), 1) || 0;
+}