@drawcall/lod 0.2.0 → 0.4.0

package/dist/{mesh/codec.js → codec/mesh.js}

@@ -1,7 +1,10 @@
-import { gzipSync, strFromU8, strToU8 } from "fflate";
-import { BufferAttribute, BufferGeometry, Float16BufferAttribute, FloatType, Group, IntType, Mesh, Object3D, Scene, } from "three/webgpu";
-import { borrowMaterials } from "../dispose.js";
+import { MeshoptEncoder } from "meshoptimizer";
+import { Box3, BufferAttribute, BufferGeometry, Float16BufferAttribute, FloatType, Group, IntType, Mesh, Object3D, Scene, Sphere, Vector3, } from "three/webgpu";
+import { pack, unpack } from "./container.js";
+import { meshoptDecoder } from "../meshopt.js";
 import { isInstancedMesh, isLOD, isMesh, isSkinnedMesh } from "../three.js";
+// The file format of a simplified level: a static hierarchy's geometry and material slots, drawn with its source's
+// materials.
 const arrays = {
     Int8Array,
     Uint8Array,
@@ -14,12 +17,17 @@ const arrays = {
     Float64Array,
 };
 const containers = { Scene, Group, Object3D };
-/** Store a static hierarchy's geometry and material slots. Decode with the same ordered material list; materials and textures are never serialized. */
-export function encodeMesh(object, materials) {
-    const chunks = [];
+/** The significant bits a float attribute holds, of its 24: each value moves by at most 2^-17 of its magnitude. */
+const BITS = 18;
+/**
+ * Store a static hierarchy's geometry and material slots. Decode with the same ordered material list; materials and textures are never serialized.
+ * Attributes and indices are meshopt-encoded, and float attributes hold `BITS` significant bits, as meshopt's exponential filter stores them.
+ */
+export async function encodeMeshAsync(object, materials) {
+    await MeshoptEncoder.ready;
+    const files = [];
     const geometries = [];
-    let length = 0;
-    function attribute(value) {
+    function attribute(value, index) {
         if (value instanceof Float16BufferAttribute)
             fail("unsupported float16 attribute");
         const packed = value instanceof BufferAttribute ? value.array : value.array.slice(0, value.count * value.itemSize);
@@ -28,14 +36,20 @@ export function encodeMesh(object, materials) {
                 const offset = i * value.data.stride + value.offset;
                 packed.set(value.array.subarray(offset, offset + value.itemSize), i * value.itemSize);
             }
-        const offset = length;
-        chunks.push(new Uint8Array(packed.buffer, packed.byteOffset, packed.byteLength));
-        length += packed.byteLength;
+        const stride = packed.BYTES_PER_ELEMENT * value.itemSize;
+        const mode = index ? (stride === 2 || stride === 4 ? (value.count % 3 ? "INDICES" : "TRIANGLES") : null) : stride % 4 || stride > 256 ? null : "ATTRIBUTES";
+        const floats = mode === "ATTRIBUTES" && packed instanceof Float32Array ? packed : undefined;
+        const bytes = floats
+            ? MeshoptEncoder.encodeFilterExp(floats, value.count, stride, BITS, "Separate")
+            : new Uint8Array(packed.buffer, packed.byteOffset, packed.byteLength);
+        files.push(mode ? MeshoptEncoder.encodeGltfBuffer(bytes, value.count, stride, mode, 1) : bytes);
         return {
-            offset,
-            length: packed.byteLength,
+            file: files.length - 1,
             type: packed.constructor.name,
+            count: value.count,
             size: value.itemSize,
+            mode,
+            filter: floats ? "EXPONENTIAL" : null,
             normalized: value.normalized,
             gpuType: value instanceof BufferAttribute ? value.gpuType : FloatType,
         };
@@ -77,68 +91,70 @@ export function encodeMesh(object, materials) {
         if (Object.keys(value.morphAttributes).length)
             fail("cannot persist morph targets");
         return {
+            bounds: bounds(value),
             name: value.name,
             data: value.userData,
             groups: value.groups.map((group) => [group.start, group.count, group.materialIndex ?? 0]),
             range: [value.drawRange.start, value.drawRange.count === Infinity ? null : value.drawRange.count],
-            attributes: Object.fromEntries(Object.entries(value.attributes).map(([name, value]) => [name, attribute(value)])),
-            index: value.index && attribute(value.index),
+            attributes: Object.fromEntries(Object.entries(value.attributes).map(([name, value]) => [name, attribute(value, false)])),
+            index: value.index && attribute(value.index, true),
         };
     });
-    const header = strToU8(JSON.stringify({ version: 1, root, geometry }));
-    const bytes = new Uint8Array(4 + header.length + length);
-    new DataView(bytes.buffer).setUint32(0, header.length, true);
-    bytes.set(header, 4);
-    let offset = 4 + header.length;
-    for (const chunk of chunks) {
-        bytes.set(chunk, offset);
-        offset += chunk.length;
-    }
-    return gzipSync(bytes, { level: 1 });
+    return pack({ version: 3, root, geometry }, files);
 }
+/** The hierarchy `encodeMeshAsync` stored, drawn with `materials`, which stay the caller's to free. */
 export async function decodeMeshAsync(input, materials) {
-    const bytes = new Uint8Array(await new Response(new Blob([input.slice().buffer]).stream().pipeThrough(new DecompressionStream("gzip"))).arrayBuffer());
-    if (bytes.length < 4)
-        fail("missing metadata");
-    const start = 4 + new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(0, true);
-    if (start > bytes.length)
-        fail("invalid metadata length");
-    const meta = record(JSON.parse(strFromU8(bytes.subarray(4, start))));
-    if (meta.version !== 1)
-        fail("unsupported version");
-    function attribute(value) {
+    const { header, files } = await unpack(input, fail);
+    const meta = record(header);
+    if (meta.version !== 3)
+        fail("unsupported version; encode it again");
+    const decoder = meshoptDecoder();
+    async function attribute(value) {
         const meta = record(value);
         const Type = arrays[string(meta.type)] ?? fail("unsupported attribute type");
-        const offset = start + integer(meta.offset);
-        const length = integer(meta.length);
+        const file = files[integer(meta.file)] ?? fail("missing attribute file");
+        const count = integer(meta.count);
         const size = integer(meta.size);
-        if (!size || length % (Type.BYTES_PER_ELEMENT * size) || offset + length > bytes.length)
+        const stride = Type.BYTES_PER_ELEMENT * size;
+        const mode = meta.mode === null ? null : string(meta.mode);
+        const filter = meta.filter === null ? undefined : string(meta.filter);
+        if (!size || (mode === null && file.length !== count * stride))
             fail("invalid attribute length");
-        const result = new BufferAttribute(new Type(bytes.slice(offset, offset + length).buffer), size, boolean(meta.normalized));
+        const { buffer, byteOffset } = mode === null ? file : await decoder.decodeGltfBufferAsync(count, stride, file, mode, filter);
+        if (!(buffer instanceof ArrayBuffer))
+            fail("shared attribute data");
+        const array = new Type(buffer, byteOffset, count * size);
+        const result = new BufferAttribute(array, size, boolean(meta.normalized));
         if (meta.gpuType !== FloatType && meta.gpuType !== IntType)
             fail("invalid attribute gpuType");
         result.gpuType = meta.gpuType;
         return result;
     }
-    const geometries = list(meta.geometry).map((value) => {
+    const geometries = await Promise.all(list(meta.geometry).map(async (value) => {
         const meta = record(value);
         const geometry = new BufferGeometry();
         geometry.name = string(meta.name);
         geometry.userData = record(meta.data);
-        for (const [name, value] of Object.entries(record(meta.attributes)))
-            geometry.setAttribute(name, attribute(value));
+        const attributes = Object.entries(record(meta.attributes));
+        const decoded = await Promise.all(attributes.map(([, value]) => attribute(value)));
+        attributes.forEach(([name], i) => geometry.setAttribute(name, decoded[i] ?? fail("missing attribute")));
         if (meta.index !== null)
-            geometry.setIndex(attribute(meta.index));
+            geometry.setIndex(await attribute(meta.index));
         for (const value of list(meta.groups)) {
             const group = list(value);
             geometry.addGroup(integer(group[0]), integer(group[1]), integer(group[2]));
         }
         const range = list(meta.range);
         geometry.setDrawRange(integer(range[0]), range[1] === null ? Infinity : integer(range[1]));
-        geometry.computeBoundingBox();
-        geometry.computeBoundingSphere();
+        if (meta.bounds !== null) {
+            const values = list(meta.bounds).map(number);
+            if (values.length !== 10)
+                fail("invalid bounds");
+            geometry.boundingBox = new Box3().setFromArray(values.slice(0, 6));
+            geometry.boundingSphere = new Sphere(new Vector3().fromArray(values, 6), values[9]);
+        }
         return geometry;
-    });
+    }));
     const material = (value) => materials[integer(value)] ?? fail("missing source material");
     function node(value) {
         const meta = record(value);
@@ -161,12 +177,24 @@ export async function decodeMeshAsync(input, materials) {
             result.add(node(child));
         return result;
     }
-    const root = node(meta.root);
-    borrowMaterials(root);
-    return root;
+    return node(meta.root);
+}
+/**
+ * The box and sphere three computes from the positions, stored so decode does not walk them; null without positions. They
+ * bound the positions before the filter, which may move a vertex out of them by 2^-17 of its coordinates.
+ */
+function bounds(geometry) {
+    if (!geometry.getAttribute("position"))
+        return null;
+    geometry.computeBoundingBox();
+    geometry.computeBoundingSphere();
+    const { boundingBox: box, boundingSphere: sphere } = geometry;
+    if (!box || !sphere)
+        fail("missing bounds");
+    return [...box.min.toArray(), ...box.max.toArray(), ...sphere.center.toArray(), sphere.radius];
 }
-function fail(reason) {
-    throw new Error(`Invalid mesh cache (${reason})`);
+function fail(reason, cause) {
+    throw new Error(`Invalid mesh cache (${reason})`, { cause });
 }
 function record(value) {
     if (typeof value !== "object" || value === null || Array.isArray(value))
@@ -189,4 +217,4 @@ function integer(value) {
     const result = number(value);
     return Number.isSafeInteger(result) && result >= 0 ? result : fail("expected nonnegative integer");
 }
-//# sourceMappingURL=codec.js.map
+//# sourceMappingURL=mesh.js.map

package/dist/codec/mesh.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mesh.js","sourceRoot":"","sources":["../../src/codec/mesh.ts"],"names":[],"mappings":"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"}

package/dist/dispose.d.ts

@@ -1,9 +1,12 @@
 import type { Object3D } from "three/webgpu";
-/** Derived geometry keeps its source materials; their owner releases them. */
-export declare function borrowMaterials(root: Object3D): void;
 /** Clones share source geometry, materials and textures; only their own draw state is released here. */
 export declare function disposeCopies(node: Object3D): void;
-/** Free what `node` and its descendants hold; a nested LOD or an ImpostorMesh frees itself. */
-export declare function disposeTree(node: Object3D): void;
+/** What `disposeRecursive` frees beside geometry and draw state. */
+export interface DisposeOptions {
+    /** whether the tree's materials and their textures are its own; false for a tree drawn with its source's, as a simplified level is */
+    materials: boolean;
+}
+/** Free what `node` and its descendants hold; a LOD or an ImpostorMesh frees itself. */
+export declare function disposeRecursive(node: Object3D, { materials }?: DisposeOptions): void;
 /** Cleanup must not replace the failure that rejected a load or prevent the other levels from being released. */
-export declare function disposeRejected(node: Object3D): void;
+export declare function disposeRejected(node: Object3D, options?: DisposeOptions): void;

package/dist/dispose.js

@@ -1,41 +1,39 @@
-import { originalOf } from "./material.js";
+import { originalOf } from "./levels/material.js";
 import { isGLTSScene, isImpostorMesh, isInstancedMesh, isLOD, isMesh, isTexture } from "./three.js";
-const borrowed = new WeakSet();
-/** Derived geometry keeps its source materials; their owner releases them. */
-export function borrowMaterials(root) {
-    root.traverse((node) => {
-        if (isMesh(node))
-            borrowed.add(node);
-    });
-}
+// Freeing what a tree of objects holds: whoever made a tree frees it, and only what it made.
 /** Clones share source geometry, materials and textures; only their own draw state is released here. */
 export function disposeCopies(node) {
-    if ((isImpostorMesh(node) || isLOD(node)) && "dispose" in node && typeof node.dispose === "function") {
+    if (isImpostorMesh(node) || isLOD(node)) {
         node.dispose();
         return;
     }
+    // An InstancedMesh's clone has instance buffers of its own. Any other node fires what Object3D.dispose fires, which frees
+    // its draw state: a subclass's own dispose may free what the clone shares.
     if (isInstancedMesh(node))
         node.dispose();
+    else
+        node.dispatchEvent({ type: "dispose" });
     for (const child of node.children)
         disposeCopies(child);
 }
-/** Free what `node` and its descendants hold; a nested LOD or an ImpostorMesh frees itself. */
-export function disposeTree(node) {
-    // ImpostorMesh, InstancedMesh, a nested Lod, a GLTS scene.
-    if ("dispose" in node && typeof node.dispose === "function") {
-        node.dispose();
-        if (isImpostorMesh(node) || isLOD(node) || isGLTSScene(node))
-            return;
-    }
+/** Free what `node` and its descendants hold; a LOD or an ImpostorMesh frees itself. */
+export function disposeRecursive(node, { materials } = { materials: true }) {
+    // Every object frees its draw state; an ImpostorMesh, a Lod and a GLTS scene free the rest too.
+    node.dispose();
+    if (isImpostorMesh(node) || isLOD(node) || isGLTSScene(node))
+        return;
     if (isMesh(node)) {
         node.geometry.dispose();
-        if (!borrowed.has(node))
+        if (materials)
             disposeMaterials(node);
     }
     for (const child of node.children)
-        disposeTree(child);
+        disposeRecursive(child, { materials });
 }
-/** Free `mesh`'s materials and their textures: the originals of level copies, which free their copies (see `levelMaterial`). */
+/**
+ * Free `mesh`'s materials and their textures: the originals of level copies, which free their copies (see
+ * `levelMaterial`). Images stay open: another object, or three's Cache, may share them and upload them again.
+ */
 function disposeMaterials(mesh) {
     for (const material of new Set([mesh.material].flat().map(originalOf))) {
         const values = Object.values(material);
@@ -46,12 +44,12 @@ function disposeMaterials(mesh) {
     }
 }
 /** Cleanup must not replace the failure that rejected a load or prevent the other levels from being released. */
-export function disposeRejected(node) {
+export function disposeRejected(node, options) {
     try {
-        disposeTree(node);
+        disposeRecursive(node, options);
     }
     catch (error) {
-        console.error("LodLoader: failed to dispose a rejected load", error);
+        console.error("CachedLodLoader: failed to dispose a rejected load", error);
     }
 }
 //# sourceMappingURL=dispose.js.map

package/dist/dispose.js.map

@@ -1 +1 @@
-{"version":3,"file":"dispose.js","sourceRoot":"","sources":["../src/dispose.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEpG,MAAM,QAAQ,GAAG,IAAI,OAAO,EAAQ,CAAC;AAErC,8EAA8E;AAC9E,MAAM,UAAU,eAAe,CAAC,IAAc;IAC5C,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,EAAE;QACrB,IAAI,MAAM,CAAC,IAAI,CAAC;YAAE,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACvC,CAAC,CAAC,CAAC;AACL,CAAC;AAED,wGAAwG;AACxG,MAAM,UAAU,aAAa,CAAC,IAAc;IAC1C,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,SAAS,IAAI,IAAI,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;QACrG,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,OAAO;IACT,CAAC;IACD,IAAI,eAAe,CAAC,IAAI,CAAC;QAAE,IAAI,CAAC,OAAO,EAAE,CAAC;IAC1C,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ;QAAE,aAAa,CAAC,KAAK,CAAC,CAAC;AAC1D,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,WAAW,CAAC,IAAc;IACxC,2DAA2D;IAC3D,IAAI,SAAS,IAAI,IAAI,IAAI,OAAO,IAAI,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;QAC5D,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,WAAW,CAAC,IAAI,CAAC;YAAE,OAAO;IACvE,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QACjB,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;QACxB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,gBAAgB,CAAC,IAAI,CAAC,CAAC;IAClD,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ;QAAE,WAAW,CAAC,KAAK,CAAC,CAAC;AACxD,CAAC;AAED,gIAAgI;AAChI,SAAS,gBAAgB,CAAC,IAAU;IAClC,KAAK,MAAM,QAAQ,IAAI,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC;QACvE,MAAM,MAAM,GAAc,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAClD,KAAK,MAAM,KAAK,IAAI,MAAM;YAAE,IAAI,SAAS,CAAC,KAAK,CAAC;gBAAE,KAAK,CAAC,OAAO,EAAE,CAAC;QAClE,QAAQ,CAAC,OAAO,EAAE,CAAC;IACrB,CAAC;AACH,CAAC;AAED,iHAAiH;AACjH,MAAM,UAAU,eAAe,CAAC,IAAc;IAC5C,IAAI,CAAC;QACH,WAAW,CAAC,IAAI,CAAC,CAAC;IACpB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,8CAA8C,EAAE,KAAK,CAAC,CAAC;IACvE,CAAC;AACH,CAAC"}
+{"version":3,"file":"dispose.js","sourceRoot":"","sources":["../src/dispose.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEpG,6FAA6F;AAE7F,wGAAwG;AACxG,MAAM,UAAU,aAAa,CAAC,IAAc;IAC1C,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACxC,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,OAAO;IACT,CAAC;IACD,0HAA0H;IAC1H,2EAA2E;IAC3E,IAAI,eAAe,CAAC,IAAI,CAAC;QAAE,IAAI,CAAC,OAAO,EAAE,CAAC;;QACrC,IAAI,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;IAC7C,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ;QAAE,aAAa,CAAC,KAAK,CAAC,CAAC;AAC1D,CAAC;AAQD,wFAAwF;AACxF,MAAM,UAAU,gBAAgB,CAAC,IAAc,EAAE,EAAE,SAAS,KAAqB,EAAE,SAAS,EAAE,IAAI,EAAE;IAClG,gGAAgG;IAChG,IAAI,CAAC,OAAO,EAAE,CAAC;IACf,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,WAAW,CAAC,IAAI,CAAC;QAAE,OAAO;IACrE,IAAI,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC;QACjB,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;QACxB,IAAI,SAAS;YAAE,gBAAgB,CAAC,IAAI,CAAC,CAAC;IACxC,CAAC;IACD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ;QAAE,gBAAgB,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC;AAC5E,CAAC;AAED;;;GAGG;AACH,SAAS,gBAAgB,CAAC,IAAU;IAClC,KAAK,MAAM,QAAQ,IAAI,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC;QACvE,MAAM,MAAM,GAAc,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAClD,KAAK,MAAM,KAAK,IAAI,MAAM;YAAE,IAAI,SAAS,CAAC,KAAK,CAAC;gBAAE,KAAK,CAAC,OAAO,EAAE,CAAC;QAClE,QAAQ,CAAC,OAAO,EAAE,CAAC;IACrB,CAAC;AACH,CAAC;AAED,iHAAiH;AACjH,MAAM,UAAU,eAAe,CAAC,IAAc,EAAE,OAAwB;IACtE,IAAI,CAAC;QACH,gBAAgB,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAClC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CAAC,oDAAoD,EAAE,KAAK,CAAC,CAAC;IAC7E,CAAC;AACH,CAAC"}

package/dist/foliage.d.ts

@@ -0,0 +1,32 @@
+import { Color, MeshStandardNodeMaterial, PhysicalLightingModel, type ColorRepresentation, type Material, type Object3D } from "three/webgpu";
+export interface FoliageOptions {
+    /** Share of sunlight a leaf passes on to its shaded side (0–1). */
+    translucency: number;
+    /** Colour of the transmitted light relative to the leaf's own: thin leaves glow yellow-green. Default #e4ff8a. */
+    tint?: ColorRepresentation;
+}
+/**
+ * A leaf material, lit with translucency: sunlight hitting the far side of a thin leaf shows on the near side, so
+ * back-lit leaves glow instead of turning black. It rides on the direct-light term, so it is shadowed exactly like front
+ * light. Set up by `foliage`. Its own class so that the copies levels draw with (clones) keep it.
+ */
+export declare class Foliage extends MeshStandardNodeMaterial {
+    translucency: number;
+    readonly tint: Color;
+    copy(source: Material): this;
+    setupLightingModel(): PhysicalLightingModel;
+    customProgramCacheKey(): string;
+}
+/**
+ * Makes `material` foliage with `options`. Cut-out leaves also get alpha to coverage and a mip-dependent alpha boost, in
+ * the view and in shadow maps alike: plain alpha testing loses coverage in smaller mips, which makes distant needles and
+ * leaves vanish.
+ */
+export declare function foliage(material: Foliage, { translucency, tint }: FoliageOptions): Foliage;
+/** Turns every alpha-tested standard material under `root`, such as a loaded plant model's leaves, into foliage. */
+export declare function foliageModel(root: Object3D, options: FoliageOptions): void;
+/**
+ * Adds leaf translucency to the lighting of the impostors under `root`, such as an `onLevel` level: the bake holds no
+ * light passing through a leaf.
+ */
+export declare function foliageLevels(root: Object3D, { translucency, tint }: FoliageOptions): void;

package/dist/foliage.js

@@ -0,0 +1,137 @@
+import { Color, ConvertNode, MeshStandardNodeMaterial, PhysicalLightingModel, TSL, } from "three/webgpu";
+import { Fn, color, dFdx, dFdy, dot, log2, materialColor, materialOpacity, max, normalView, positionViewDirection, pow, saturate, uv, vec2, vec3, vec4, } from "three/tsl";
+import { cosine } from "./impostor/mesh/surface.js";
+import { isImpostorMesh, isMesh, isShadowPass, isStandard } from "./three.js";
+import { isNodeOf } from "./tsl.js";
+const TINT = "#e4ff8a";
+/**
+ * A leaf material, lit with translucency: sunlight hitting the far side of a thin leaf shows on the near side, so
+ * back-lit leaves glow instead of turning black. It rides on the direct-light term, so it is shadowed exactly like front
+ * light. Set up by `foliage`. Its own class so that the copies levels draw with (clones) keep it.
+ */
+export class Foliage extends MeshStandardNodeMaterial {
+    translucency = 0;
+    tint = new Color(1, 1, 1);
+    copy(source) {
+        super.copy(source);
+        // NodeMaterial.copy skips Material accessors, including the cutout threshold.
+        this.alphaTest = source.alphaTest;
+        if (source instanceof Foliage) {
+            this.translucency = source.translucency;
+            this.tint.copy(source.tint);
+        }
+        return this;
+    }
+    setupLightingModel() {
+        return new Translucent(transmitted(leafBehind, this.translucency, this.tint));
+    }
+    // The lighting model is no node: materials alike in their nodes would share a shader.
+    customProgramCacheKey() {
+        return `${super.customProgramCacheKey()}|foliage-${this.translucency}-${this.tint.getHexString()}`;
+    }
+}
+/**
+ * Makes `material` foliage with `options`. Cut-out leaves also get alpha to coverage and a mip-dependent alpha boost, in
+ * the view and in shadow maps alike: plain alpha testing loses coverage in smaller mips, which makes distant needles and
+ * leaves vanish.
+ */
+export function foliage(material, { translucency, tint = TINT }) {
+    material.translucency = translucency;
+    material.tint.set(tint);
+    if (!(material.alphaTest > 0 && material.map))
+        return material;
+    material.alphaToCoverage = true;
+    const boost = boostOf(material.map);
+    material.opacityNode = materialOpacity.mul(boost);
+    // A shadow pass multiplies the map's alpha by the colour's: there the colour is the boost alone.
+    material.colorNode = Fn((builder) => (isShadowPass(builder.material) ? vec4(vec3(1), boost) : baseColor))();
+    return material;
+}
+/** Turns every alpha-tested standard material under `root`, such as a loaded plant model's leaves, into foliage. */
+export function foliageModel(root, options) {
+    const made = new Map();
+    const swap = (material) => {
+        if (!isStandard(material) || material.alphaTest === 0)
+            return material;
+        let leaf = made.get(material);
+        if (!leaf)
+            made.set(material, (leaf = foliage(new Foliage().copy(material), options)));
+        return leaf;
+    };
+    root.traverse((node) => {
+        if (isMesh(node))
+            node.material = Array.isArray(node.material) ? node.material.map(swap) : swap(node.material);
+    });
+}
+/**
+ * Adds leaf translucency to the lighting of the impostors under `root`, such as an `onLevel` level: the bake holds no
+ * light passing through a leaf.
+ */
+export function foliageLevels(root, { translucency, tint = TINT }) {
+    const shade = new Color(tint);
+    root.traverse((node) => {
+        if (!isImpostorMesh(node))
+            return;
+        const { material } = node;
+        // The mean over the leaves a texel averages: its one unit normal would light them all one way.
+        material.directTerm = transmitted((direction) => cosine(material.spread, direction.negate()), translucency, shade);
+    });
+}
+/**
+ * A material's colour times its map, its alpha included: three's `materialColor`, which builds to a vec4 where the
+ * material has a map, and to a vec3 (typed so) where not.
+ */
+const baseColor = Fn(() => {
+    const base = vec4(1).toVar();
+    base.assign(materialColor);
+    return base;
+})();
+/** Boosts alpha by the mip `map` is read at. */
+function boostOf(map) {
+    const image = map.image;
+    if (typeof image !== "object" ||
+        image === null ||
+        !("width" in image) ||
+        !("height" in image) ||
+        typeof image.width !== "number" ||
+        typeof image.height !== "number")
+        throw new Error(`@drawcall/lod: the leaves' map "${map.name}" has no image to measure`);
+    const texel = uv().mul(vec2(image.width, image.height));
+    const mip = max(log2(max(dot(dFdx(texel), dFdx(texel)), dot(dFdy(texel), dFdy(texel)))).mul(0.5), 0);
+    return mip.mul(0.25).add(1);
+}
+/** The share of a leaf's sunlight arriving on its far side, by its normal. */
+const leafBehind = (direction) => saturate(dot(normalView, direction).negate());
+/**
+ * The light passing through a leaf from a direct light in `direction`, of that light × the leaf's colour: `behind` the
+ * share arriving on its far side.
+ */
+function transmitted(behind, share, tint) {
+    return (direction) => {
+        // light scatters forward through the leaf: strongest when looking toward the sun
+        const forward = pow(saturate(dot(positionViewDirection, direction.negate())), 3)
+            .mul(0.65)
+            .add(0.35);
+        return behind(direction).mul(forward).mul(share).mul(color(tint));
+    };
+}
+/** Three's lighting with `term` of each direct light's direction added, of that light × the surface's colour. */
+class Translucent extends PhysicalLightingModel {
+    term;
+    constructor(term) {
+        super();
+        this.term = term;
+    }
+    direct(input, builder) {
+        super.direct(input, builder);
+        const { lightDirection, lightColor, reflectedLight } = input;
+        const { directDiffuse } = reflectedLight;
+        if (!isNodeOf(lightDirection, "vec3", builder) || !isNodeOf(directDiffuse, "vec3", builder))
+            throw new Error("@drawcall/lod: three's direct light is not a direction and a sum");
+        // Converted, not asked its type: asked here, before its shadow is set up, three (0.186) answers a colour, keeps
+        // that, and writes invalid WGSL for the shadow's vec4.
+        const light = vec3(new ConvertNode(lightColor, "vec3"));
+        directDiffuse.addAssign(this.term(lightDirection).mul(light).mul(TSL.diffuseContribution));
+    }
+}
+//# sourceMappingURL=foliage.js.map

package/dist/foliage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"foliage.js","sourceRoot":"","sources":["../src/foliage.ts"],"names":[],"mappings":"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"}

package/dist/impostor/bake/atlas.d.ts

@@ -4,11 +4,11 @@ import type { ImpostorMap } from "../impostor.js";
  * The bake stores the normals two ways (see its materials): the maps hold the surface's
  * own normals, `turned` the shading normals turned toward the camera, each with the share
  * of the surface that shades with the normal rather than its opposite (in orm.a). One way
- * is kept for the whole impostor, as texels filtered together must mean the same thing.
+ * serves the whole impostor, as texels filtered together must mean the same thing.
  * With `specular`, the bake also writes each surface's dielectric specular, of which only
- * the coverage-weighted sum is kept, for its mean.
+ * the coverage-weighted sum is stored, for its mean.
  */
-export declare class Atlas {
+export declare class ImpostorAtlasMip {
     readonly maps: ImpostorMap[];
     readonly frames: number;
     readonly cell: number;
@@ -26,7 +26,7 @@ export declare class Atlas {
     /** F0 RGB and F90 summed over the texels by coverage, and the coverage summed. */
     private readonly specularSum;
     constructor(maps: ImpostorMap[], frames: number, cell: number, specular: boolean);
-    /** Keep the turned normals: write them over the own normals and their shares. */
+    /** Use the turned normals: write them over the own normals and their shares. */
     useTurned(): void;
     private layer;
     /**

package/dist/impostor/bake/atlas.js

@@ -11,11 +11,11 @@ const NEIGHBOURS = [
  * The bake stores the normals two ways (see its materials): the maps hold the surface's
  * own normals, `turned` the shading normals turned toward the camera, each with the share
  * of the surface that shades with the normal rather than its opposite (in orm.a). One way
- * is kept for the whole impostor, as texels filtered together must mean the same thing.
+ * serves the whole impostor, as texels filtered together must mean the same thing.
  * With `specular`, the bake also writes each surface's dielectric specular, of which only
- * the coverage-weighted sum is kept, for its mean.
+ * the coverage-weighted sum is stored, for its mean.
  */
-export class Atlas {
+export class ImpostorAtlasMip {
     maps;
     frames;
     cell;
@@ -39,7 +39,7 @@ export class Atlas {
         this.coverage = new Float32Array(this.size * this.size);
         this.turned = new Uint8Array(this.size * this.size * 4);
     }
-    /** Keep the turned normals: write them over the own normals and their shares. */
+    /** Use the turned normals: write them over the own normals and their shares. */
     useTurned() {
         const normalDepth = this.layer("normalDepth");
         const orm = this.layer("orm");
@@ -52,7 +52,7 @@ export class Atlas {
     layer(map) {
         const layer = this.layers[this.maps.indexOf(map)];
         if (!layer)
-            throw new Error(`Atlas: no ${map} layer`);
+            throw new Error(`ImpostorAtlasMip: no ${map} layer`);
         return layer;
     }
     /**
@@ -66,7 +66,7 @@ export class Atlas {
         const { cell, size, maps, layers } = this;
         const [alpha] = pixels;
         if (!alpha || pixels.length !== maps.length + (this.specular ? 2 : 1))
-            throw new Error("Atlas.write: one pixel array per map, then the turned normals, then the specular if baked");
+            throw new Error("ImpostorAtlasMip.write: one pixel array per map, then the turned normals, then the specular if baked");
         const sources = [...maps, "turned"];
         const specular = this.specular ? pixels[maps.length + 1] : undefined;
         for (let y = 0; y < cell; y++)
@@ -104,7 +104,7 @@ export class Atlas {
                     const source = pixels[m];
                     const layer = map === "turned" ? this.turned : layers[m];
                     if (!source || !layer)
-                        throw new Error(`Atlas.write: no pixels for ${map}`);
+                        throw new Error(`ImpostorAtlasMip.write: no pixels for ${map}`);
                     const [r, g, b, a] = average(source);
                     if (map === "normalDepth")
                         this.agreement.own += cover * Math.hypot(r * 2 - 1, g * 2 - 1, b * 2 - 1);
@@ -118,7 +118,7 @@ export class Atlas {
     meanSpecular() {
         const { value, coverage } = this.specularSum;
         if (!this.specular || coverage === 0)
-            throw new Error("Atlas.meanSpecular: no specular was baked");
+            throw new Error("ImpostorAtlasMip.meanSpecular: no specular was baked");
         const [r = 0, g = 0, b = 0, f90 = 0] = value.map((v) => v / coverage);
         return [r, g, b, f90];
     }
@@ -162,7 +162,7 @@ export class Atlas {
                 filled[ny * cell + nx] = 1;
                 queue[tail++] = ny * cell + nx;
                 const to = ((y0 + ny) * size + x0 + nx) * 4;
-                // Base keeps zero coverage; the other layers' alpha is data (depth) and spreads too.
+                // Base coverage stays zero; the other layers' alpha is data (depth) and spreads too.
                 this.layers.forEach((layer, m) => {
                     const n = this.maps[m] === "base" ? 3 : 4;
                     for (let k = 0; k < n; k++)
@@ -176,9 +176,9 @@ export class Atlas {
 }
 /**
  * Pack one texel into `layer` at byte `out`: colour as sRGB if `srgb`, the rest linearly.
- * An averaged normal keeps its length, which says how far the normals it averages agree
- * and is lit by: renormalised, a texel of leaves facing every which way would light as one
- * smooth surface turned to the camera.
+ * An averaged normal is not renormalised: its length says how far the normals it averages
+ * agree, and is lit by. Renormalised, a texel of leaves facing every which way would light
+ * as one smooth surface turned to the camera.
  */
 function store(layer, out, [r, g, b, a], srgb) {
     const encode = srgb ? toSrgb : (v) => Math.round(v * 255);