@woosh/meep-engine 3.57.0 → 3.59.0

package/src/generation/foliage/asset/TreeSpeciesCache.js

@@ -0,0 +1,147 @@
+import { HashMap } from "../../../core/collection/map/HashMap.js";
+import { TreeSpeciesConfig } from "../config/TreeSpeciesConfig.js";
+import { FoliageAtlasCutout } from "../material/FoliageAtlasCutout.js";
+import { make_bark_material } from "../material/make_bark_material.js";
+import { make_foliage_material } from "../material/make_foliage_material.js";
+import { tree_shoot_prototypes } from "./tree_shoot_prototypes.js";
+
+/**
+ * What every tree of a species shares, whatever its seed or how it grew: its bark material, its leaf atlas and its
+ * shoot prototypes, each made once, when a tree first asks for it (`generate_tree`'s `cache`). The caller owns it,
+ * and what it holds lives as long as it does.
+ *
+ * Each is keyed on exactly what it is made from: the bark material on the species' `bark_material`, the leaf atlas on
+ * its `foliage` and `foliage_material`, made from a species holding those alone, and the prototypes on the whole
+ * species but its seed, as they grow on its own framework. Trees that differ in nothing one is made from share it.
+ */
+export class TreeSpeciesCache {
+    /**
+     * Each bark material, by the `bark_material` it is made from.
+     * @type {HashMap<import("../config/BarkMaterialConfig.js").BarkMaterialConfig, import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial>}
+     */
+    #barks = new HashMap();
+
+    /**
+     * Each leaf atlas, by the species it is made from: one holding its `foliage` and `foliage_material` alone.
+     * @type {HashMap<TreeSpeciesConfig, {material: import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial, cutout: FoliageAtlasCutout}>}
+     */
+    #leaves = new HashMap();
+
+    /**
+     * Each species' shoot prototypes, by the species at their seed, then by the leaf material they are drawn with.
+     * @type {HashMap<TreeSpeciesConfig, Map<import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial, import("./tree_shoot_prototypes.js").TreeShootPrototypes>>}
+     */
+    #prototypes = new HashMap();
+    #prototype_count = 0;
+
+    /**
+     * Lets go of everything held: the trees already made keep what they drew with.
+     */
+    clear() {
+        this.#barks.clear();
+        this.#leaves.clear();
+        this.#prototypes.clear();
+        this.#prototype_count = 0;
+    }
+
+    /**
+     * Number of bark materials held.
+     * @returns {number}
+     */
+    get bark_count() {
+        return this.#barks.size;
+    }
+
+    /**
+     * Number of leaf atlases held.
+     * @returns {number}
+     */
+    get leaf_count() {
+        return this.#leaves.size;
+    }
+
+    /**
+     * Number of species whose shoot prototypes are held.
+     * @returns {number}
+     */
+    get prototype_count() {
+        return this.#prototype_count;
+    }
+
+    /**
+     * The bark material of `species`, the same noise for every bark (`make_bark_material`'s own seed).
+     *
+     * @param {TreeSpeciesConfig} species
+     * @returns {import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial}
+     */
+    bark_material(species) {
+        let material = this.#barks.get(species.bark_material);
+        if (material === undefined) {
+            const held = species.bark_material.clone();
+            material = make_bark_material(held);
+            this.#barks.set(held, material);
+        }
+        return material;
+    }
+
+    /**
+     * The leaf atlas of `species`, in the species' leaf material, which a tree clones to tint its own, and the atlas's
+     * shape.
+     *
+     * @param {TreeSpeciesConfig} species
+     * @returns {{material: import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial, cutout: FoliageAtlasCutout}}
+     */
+    leaves(species) {
+        // the species as far as its leaves go, and no further: whatever the atlas reads, it reads from the key
+        const key = new TreeSpeciesConfig();
+        key.seed = 0;
+        key.foliage.copy(species.foliage);
+        key.foliage_material.copy(species.foliage_material);
+        let entry = this.#leaves.get(key);
+        if (entry === undefined) {
+            const cutout = new FoliageAtlasCutout();
+            entry = { material: make_foliage_material(key, cutout), cutout };
+            this.#leaves.set(key, entry);
+        }
+        return entry;
+    }
+
+    /**
+     * The shoot prototypes of `species` (`tree_shoot_prototypes`), whatever its seed, their cuts baked from the leaves
+     * of `material`: its own leaf atlas (`leaves`) by default, or a caller's own material, whose atlas has no fitted
+     * shape (`cutout` null).
+     *
+     * @param {TreeSpeciesConfig} species
+     * @param {import("../../../shade/renderer/material/StandardShadeMaterial.js").StandardShadeMaterial|null} [material]
+     * @param {FoliageAtlasCutout|null} [cutout] the shape of `material`'s atlas
+     * @returns {import("./tree_shoot_prototypes.js").TreeShootPrototypes}
+     */
+    prototypes(species, material = null, cutout = null) {
+        if (material === null) {
+            const leaves = this.leaves(species);
+            material = leaves.material;
+            cutout = leaves.cutout;
+        }
+        const key = species.clone();
+        key.seed = 0;
+        let by_material = this.#prototypes.get(key);
+        if (by_material === undefined) {
+            by_material = new Map();
+            this.#prototypes.set(key, by_material);
+        }
+        let prototypes = by_material.get(material);
+        if (prototypes === undefined) {
+            prototypes = tree_shoot_prototypes(key, material, cutout);
+            by_material.set(material, prototypes);
+            this.#prototype_count++;
+        }
+        return prototypes;
+    }
+}
+
+/**
+ * The cache `generate_tree` shares between the trees it is asked for without one of their own: each species' materials and
+ * shoot prototypes are made once, the first time a tree asks, and held until `clear`ed.
+ * @type {TreeSpeciesCache}
+ */
+export const TREE_SPECIES_CACHE = new TreeSpeciesCache();

package/src/generation/foliage/asset/generate_tree.d.ts

@@ -7,6 +7,27 @@
  * - A `TreeSpeciesConfig` instance (`generate_tree(species_config)`).
  * - An options object (`generate_tree({ preset: "birch", seed: 42, crown: { height: 14 }, lod_count: 3 })`).
  *
+ * The options object also picks how the tree is grown, `growth` (`TreeGrowth`, by its generator graph unless given):
+ * its generator graph's framework with its species' shoot prototypes drawn on it, for most trees; or that framework
+ * with every shoot system grown on it, for trees seen up close. Both are drawn by one pipeline. A species is described
+ * for the front end that grows it (`make_tree_species_preset`'s `growth`): a preset's name is described for `growth`;
+ * a caller's own `TreeSpeciesConfig` is grown as it is, by the generator graph when passed alone, or by `growth` when
+ * passed as the options object's `species`. Its `cache`, a
+ * `TreeSpeciesCache`, shares each species' bark material, leaf atlas and shoot prototypes between the trees it grows;
+ * without one, every call shares `TREE_SPECIES_CACHE`. A caller's own materials (`custom_bark_material`,
+ * `custom_foliage_material`) are drawn with instead.
+ *
+ * Each LOD is the tree drawn to a geometric error (`TreeLODConfig.error`): the finest at which its bark and its
+ * foliage, and its wind joints, fit that LOD's `TREE_RENDER_COST_CEILING` over the side area of the leaves and wood
+ * the tree grew (`tree_lod_plan`, `tree_grown_side_area`). Its foliage is one card per cluster (`tree_clusters`), each
+ * drawn with the tile of one of a few cuts (`tree_cluster_representatives`), shared by all its LODs in one atlas as
+ * large as the tree's texture ceiling: baked from the leaves and twigs that cut grew (`tree_cluster_bake`) at the
+ * leaf's own texel, or for a coarser LOD's cut, where the LOD before it is drawn to a pixel. Its rig is on the wood it draws, at a tolerance no finer than its
+ * error, its joints a subset of the finer LOD's, so switching keeps the joints both share.
+ *
+ * The asset's `foliage_material` and `skin_info` are the leaves' and the wood's as grown, which the cards are baked
+ * from and the leaves are bound to; each LOD has its own.
+ *
  * @param {string|import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig|Object} [options={}]
  * @returns {TreeAsset}
  */

package/src/generation/foliage/asset/generate_tree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate_tree.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/asset/generate_tree.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;GAWG;AACH,wCAHW,MAAM,GAAC,OAAO,gCAAgC,EAAE,iBAAiB,MAAO,GACtE,SAAS,CAqFrB;0BAlGyB,gBAAgB"}
+{"version":3,"file":"generate_tree.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/asset/generate_tree.js"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wCAHW,MAAM,GAAC,OAAO,gCAAgC,EAAE,iBAAiB,MAAO,GACtE,SAAS,CA6JrB;0BAlMyB,gBAAgB"}

package/src/generation/foliage/asset/generate_tree.js

@@ -1,16 +1,25 @@
+import { assert } from "../../../core/assert.js";
+import { TREE_RENDER_COST_CEILING, tree_grown_side_area } from "../analysis/tree_render_cost.js";
 import { build_tree_wind_rig } from "../animation/build_tree_wind_rig.js";
+import { TREE_LOD_ERROR_FINEST } from "../config/TreeLODConfig.js";
+import { TreeGrowth } from "../config/TreeGrowth.js";
 import { TreePreset } from "../config/TreePreset.js";
-import { FoliageAtlasCutout } from "../material/FoliageAtlasCutout.js";
-import { make_bark_material } from "../material/make_bark_material.js";
-import { make_foliage_material } from "../material/make_foliage_material.js";
+import { tree_cluster_atlas } from "../material/tree_cluster_atlas.js";
 import { foliage_collect_attachments } from "../mesh/foliage_collect_attachments.js";
-import { tree_mesh_build_bark } from "../mesh/tree_mesh_build_bark.js";
+import { tree_clusters } from "../mesh/tree_clusters.js";
+import { tree_mesh_build_bark, tree_mesh_compute_branch_rings } from "../mesh/tree_mesh_build_bark.js";
+import { tree_mesh_build_clusters } from "../mesh/tree_mesh_build_clusters.js";
 import { tree_mesh_build_foliage } from "../mesh/tree_mesh_build_foliage.js";
 import { make_tree_species_preset } from "../presets/make_tree_species_preset.js";
 import { tree_skeleton_assign_skin_joints } from "../skeleton/tree_skeleton_assign_skin_joints.js";
+import { tree_skeleton_bind_skin_joints } from "../skeleton/tree_skeleton_bind_skin_joints.js";
 import { tree_skeleton_grow } from "../skeleton/tree_skeleton_grow.js";
+import { tree_skeleton_grow_framework } from "../skeleton/tree_skeleton_grow_framework.js";
 import { TreeAsset } from "./TreeAsset.js";
 import { TreeLODAsset } from "./TreeLODAsset.js";
+import { TREE_SPECIES_CACHE } from "./TreeSpeciesCache.js";
+import { tree_shoot_instance_card_count, tree_shoot_instance_cards, tree_shoot_instance_leaves, tree_shoot_instances } from "./tree_shoot_instances.js";
+import { tree_lod_plan } from "./tree_lod_plan.js";
 
 /**
  * Turn-key procedural tree and foliage generator.
@@ -21,6 +30,27 @@ import { TreeLODAsset } from "./TreeLODAsset.js";
  * - A `TreeSpeciesConfig` instance (`generate_tree(species_config)`).
  * - An options object (`generate_tree({ preset: "birch", seed: 42, crown: { height: 14 }, lod_count: 3 })`).
  *
+ * The options object also picks how the tree is grown, `growth` (`TreeGrowth`, by its generator graph unless given):
+ * its generator graph's framework with its species' shoot prototypes drawn on it, for most trees; or that framework
+ * with every shoot system grown on it, for trees seen up close. Both are drawn by one pipeline. A species is described
+ * for the front end that grows it (`make_tree_species_preset`'s `growth`): a preset's name is described for `growth`;
+ * a caller's own `TreeSpeciesConfig` is grown as it is, by the generator graph when passed alone, or by `growth` when
+ * passed as the options object's `species`. Its `cache`, a
+ * `TreeSpeciesCache`, shares each species' bark material, leaf atlas and shoot prototypes between the trees it grows;
+ * without one, every call shares `TREE_SPECIES_CACHE`. A caller's own materials (`custom_bark_material`,
+ * `custom_foliage_material`) are drawn with instead.
+ *
+ * Each LOD is the tree drawn to a geometric error (`TreeLODConfig.error`): the finest at which its bark and its
+ * foliage, and its wind joints, fit that LOD's `TREE_RENDER_COST_CEILING` over the side area of the leaves and wood
+ * the tree grew (`tree_lod_plan`, `tree_grown_side_area`). Its foliage is one card per cluster (`tree_clusters`), each
+ * drawn with the tile of one of a few cuts (`tree_cluster_representatives`), shared by all its LODs in one atlas as
+ * large as the tree's texture ceiling: baked from the leaves and twigs that cut grew (`tree_cluster_bake`) at the
+ * leaf's own texel, or for a coarser LOD's cut, where the LOD before it is drawn to a pixel. Its rig is on the wood it draws, at a tolerance no finer than its
+ * error, its joints a subset of the finer LOD's, so switching keeps the joints both share.
+ *
+ * The asset's `foliage_material` and `skin_info` are the leaves' and the wood's as grown, which the cards are baked
+ * from and the leaves are bound to; each LOD has its own.
+ *
  * @param {string|import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig|Object} [options={}]
  * @returns {TreeAsset}
  */
@@ -29,15 +59,21 @@ export function generate_tree(options = {}) {
     let eager_meshlets = false;
     let custom_bark_material = null;
     let custom_foliage_material = null;
+    // the generator graph unless an options object asks for another
+    let growth = TreeGrowth.Graph;
+    let cache = null;
 
     if (typeof options === "string") {
-        config = make_tree_species_preset(options);
+        config = make_tree_species_preset(options, {}, growth);
     } else if (options && options.isTreeSpeciesConfig) {
         config = options.clone();
     } else {
         const opts = options || {};
         const preset = opts.preset ?? TreePreset.Oak;
-        config = make_tree_species_preset(preset, opts);
+        growth = opts.growth ?? growth;
+        cache = opts.cache ?? null;
+        assert.enum(growth, TreeGrowth, "growth");
+        config = opts.species?.isTreeSpeciesConfig ? opts.species.clone() : make_tree_species_preset(preset, opts, growth);
         eager_meshlets = Boolean(opts.eager_meshlets);
         if (opts.custom_bark_material && opts.custom_bark_material.isShadeMaterial) {
             custom_bark_material = opts.custom_bark_material;
@@ -47,13 +83,18 @@ export function generate_tree(options = {}) {
         }
     }
 
-    const skeleton = tree_skeleton_grow(config);
+    const skeleton = growth === TreeGrowth.Graph ? tree_skeleton_grow_framework(config) : tree_skeleton_grow(config);
+    // what every tree of its species shares, made only where the caller gave none of its own
+    const species_cache = cache ?? TREE_SPECIES_CACHE;
+    // a tree grown by its generator graph draws its species' shoot prototypes on its carriers
+    const prototypes = growth === TreeGrowth.Graph && config.shoot_rules.length > 0
+        ? species_cache.prototypes(config, custom_foliage_material)
+        : null;
+    const instances = prototypes !== null ? tree_shoot_instances(skeleton, prototypes) : null;
+    // the rig of all the wood as grown, which the leaves as grown are bound to
     const skin_info = tree_skeleton_assign_skin_joints(skeleton, config);
-    const wind_rig = config.wind.enabled ? build_tree_wind_rig(skin_info, config.wind) : null;
 
-    const bark_material = custom_bark_material !== null
-        ? custom_bark_material
-        : make_bark_material(config.bark_material, config.seed);
+    const bark_material = custom_bark_material !== null ? custom_bark_material : species_cache.bark_material(config);
 
     // The atlas's shape sets how many cards a shoot carries and, for hull cards, their outline. A caller's own
     // material has no fitted outline, so its cards cover whole tiles, at the density our atlas would need.
@@ -62,10 +103,19 @@ export function generate_tree(options = {}) {
     if (custom_foliage_material !== null) {
         foliage_material = custom_foliage_material;
     } else if (config.foliage_rules.length > 0) {
-        foliage_cutout = new FoliageAtlasCutout();
-        foliage_material = make_foliage_material(config, foliage_cutout);
+        // the species' atlas, in a material of the tree's own, which its leaves' tints scale
+        const leaves = species_cache.leaves(config);
+        foliage_cutout = leaves.cutout;
+        foliage_material = leaves.material.clone();
+    }
+    // The cards anchor on the bark's rings at the finest LOD's error. The LOD search's first step plans the rings at
+    // TREE_LOD_ERROR_FINEST with the skeleton still bound to the rig as grown, as here: where the two errors are one,
+    // so are the rings, planned once
+    const planned = new Map();
+    if (config.lods[0]?.error === TREE_LOD_ERROR_FINEST) {
+        planned.set(TREE_LOD_ERROR_FINEST, tree_mesh_compute_branch_rings(skeleton, config, config.lods[0]));
     }
-    const attachments = foliage_collect_attachments(skeleton, config, foliage_cutout ?? undefined);
+    const attachments = foliage_collect_attachments(skeleton, config, foliage_cutout ?? undefined, planned.get(TREE_LOD_ERROR_FINEST));
     if (foliage_cutout !== null) {
         // Card tints can brighten as well as darken; the unorm8 vertex colours carry tint / tint_scale and our
         // material multiplies tint_scale back in
@@ -80,24 +130,76 @@ export function generate_tree(options = {}) {
     asset.skeleton = skeleton;
     asset.attachments = attachments;
     asset.skin_info = skin_info;
-    asset.wind_rig = wind_rig;
     asset.bark_material = bark_material;
     asset.foliage_material = foliage_material;
     asset.foliage_cutout = foliage_cutout;
 
+    // every leaf as the tree grew it: what each LOD's cluster cards are baked from, built again for each, as it would
+    // otherwise be held for as long as any LOD is not
+    const has_leaves = attachments.count > 0 && foliage_material !== null;
+    const grow_leaves = () => tree_mesh_build_foliage(skeleton, attachments, config, foliage_cutout);
+    const draws_prototypes = prototypes !== null && prototypes.atlas !== null;
+    const side_area = tree_grown_side_area(skeleton, has_leaves ? grow_leaves() : null,
+        instances !== null ? tree_shoot_instance_leaves(skeleton, instances, prototypes) : null);
+    asset.side_area = side_area;
+    asset.shoot_prototypes = prototypes;
+    asset.shoot_instances = instances;
+    const plan = tree_lod_plan(skeleton, config, attachments, side_area, config.lods.length, planned,
+        instances !== null ? (error) => tree_shoot_instance_card_count(instances, prototypes, error) : null);
+    const lod_configs = plan.map((p, i) => {
+        const lod_cfg = config.lods[i].clone();
+        lod_cfg.error = p.error;
+        return lod_cfg;
+    });
+
+    // every LOD's cluster cards drawn with a few cuts' tiles, one atlas for all of them, as many as the tree's texture
+    // ceiling holds: built with the first LOD's foliage
+    let shared = null;
+    const cluster_atlas = () => {
+        if (shared === null) {
+            shared = tree_cluster_atlas(skeleton, config, attachments, grow_leaves(), lod_configs, foliage_material,
+                TREE_RENDER_COST_CEILING.texture_density * side_area);
+        }
+        return shared;
+    };
+
     for (let i = 0; i < config.lods.length; i++) {
-        const lod_cfg = config.lods[i];
+        const lod_cfg = lod_configs[i];
+        const lod_skin = plan[i].skin_info;
         const lod_asset = new TreeLODAsset();
         lod_asset.level = i;
         lod_asset.name = config.name || "tree";
         lod_asset.configure_lazy_geometries(
-            () => tree_mesh_build_bark(skeleton, config, lod_cfg),
-            () => tree_mesh_build_foliage(skeleton, attachments, config, lod_cfg, foliage_cutout)
+            () => {
+                tree_skeleton_bind_skin_joints(skeleton, lod_skin);
+                return tree_mesh_build_bark(skeleton, config, lod_cfg);
+            },
+            () => {
+                if (instances !== null) {
+                    if (!draws_prototypes) return null;
+                    // its prototypes' cuts at its error, on its own rig
+                    tree_skeleton_bind_skin_joints(skeleton, lod_skin);
+                    const rings = tree_mesh_compute_branch_rings(skeleton, config, lod_cfg);
+                    const { clusters, cards, placement } = tree_shoot_instance_cards(skeleton, rings, instances, prototypes, lod_cfg.error);
+                    const geometry = tree_mesh_build_clusters(skeleton, config, clusters, cards, placement, prototypes.atlas.bake);
+                    if (geometry === null) return null;
+                    return { geometry, material: prototypes.atlas.material };
+                }
+                if (!has_leaves) return null;
+                tree_skeleton_bind_skin_joints(skeleton, lod_skin);
+                const clusters = tree_clusters(skeleton, attachments, tree_mesh_compute_branch_rings(skeleton, config, lod_cfg));
+                // its clusters again, on its own rig; their cards are where they were
+                const { lods, representatives, bake, material } = cluster_atlas();
+                const cards = lods[i].cards;
+                const geometry = tree_mesh_build_clusters(skeleton, config, clusters, cards, representatives.placements[i], bake);
+                if (geometry === null) return null;
+                return { geometry, material };
+            }
         );
         lod_asset.bark_material = bark_material;
-        lod_asset.foliage_material = foliage_material;
-        lod_asset.skin_info = config.wind.enabled ? skin_info : null;
-        lod_asset.wind_rig = wind_rig;
+        lod_asset.skin_info = config.wind.enabled ? lod_skin : null;
+        lod_asset.wind_rig = config.wind.enabled ? build_tree_wind_rig(lod_skin, config.wind) : null;
+        lod_asset.config = lod_cfg;
 
         if (eager_meshlets) {
             void lod_asset.prefab;

package/src/generation/foliage/asset/place_tree.d.ts

@@ -10,7 +10,8 @@
  *
  * @param {import("../../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} scene_context
  * @param {import("../../../engine/ecs/EntityComponentDataset.js").EntityComponentDataset} dataset
- * @param {Object} [options={}]
+ * @param {Object} [options={}] without a `tree` or a `prefab`, the tree is grown from these by `generate_tree` (its
+ *        `preset`, `seed`, `growth`, `cache` and the rest)
  * @param {import("./TreeAsset.js").TreeAsset} [options.tree] pre-generated `TreeAsset`
  * @param {import("../../../engine/graphics3/prefab/Prefab.js").Prefab} [options.prefab] pre-compiled `Prefab`
  * @param {number} [options.lod=0] LOD index when placing from `TreeAsset`

package/src/generation/foliage/asset/place_tree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"place_tree.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/asset/place_tree.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,0CAxBW,OAAO,kDAAkD,EAAE,eAAe,WAC1E,OAAO,+CAA+C,EAAE,sBAAsB;IAEjC,IAAI,GAAjD,OAAO,gBAAgB,EAAE,SAAS;IACoC,MAAM,GAA5E,OAAO,4CAA4C,EAAE,MAAM;IAC1C,GAAG,GAApB,MAAM;IACgB,SAAS,GAA/B,WAAW;IACqC,QAAQ,GAAxD,MAAM,EAAE,GAAC;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC;IACoB,QAAQ,GAAjE,MAAM,EAAE,GAAC;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC;IAC7B,UAAU,GAA3B,MAAM;IACiD,KAAK,GAA5D,MAAM,GAAC,MAAM,EAAE,GAAC;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC;IAC1B,IAAI,GAAtB,OAAO;IACU,WAAW,GAA5B,MAAM;IACW,iBAAiB,GAAlC,MAAM;IACJ;IACZ,IAAQ,EAAE,MAAM,CAAC;IACjB,QAAY,EAAE,OAAO,oDAAoD,EAAE,cAAc,CAAC;IAC1F,KAAS,EAAE;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC,EAAE,GAAC,IAAI,CAAC;IACpD,eAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,KAAS,EAAE,MAAM,CAAC;IAClB,IAAQ,EAAE,OAAO,gBAAgB,EAAE,SAAS,GAAC,IAAI,CAAC;IAClD,MAAU,EAAE,OAAO,4CAA4C,EAAE,MAAM,CAAA;CACpE,CA+HH;AAED;;;;;;;GAOG;AACH,4CAJW,OAAO,kDAAkD,EAAE,eAAe,WAC1E,OAAO,+CAA+C,EAAE,sBAAsB,UAC9E,WAAW,iBAAiB,CAAC,QAiBvC;4BA/L2B,8CAA8C"}
+{"version":3,"file":"place_tree.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/asset/place_tree.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,0CAzBW,OAAO,kDAAkD,EAAE,eAAe,WAC1E,OAAO,+CAA+C,EAAE,sBAAsB;IAGjC,IAAI,GAAjD,OAAO,gBAAgB,EAAE,SAAS;IACoC,MAAM,GAA5E,OAAO,4CAA4C,EAAE,MAAM;IAC1C,GAAG,GAApB,MAAM;IACgB,SAAS,GAA/B,WAAW;IACqC,QAAQ,GAAxD,MAAM,EAAE,GAAC;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC;IACoB,QAAQ,GAAjE,MAAM,EAAE,GAAC;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC;IAC7B,UAAU,GAA3B,MAAM;IACiD,KAAK,GAA5D,MAAM,GAAC,MAAM,EAAE,GAAC;QAAC,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAC;QAAA,CAAC,EAAC,MAAM,CAAA;KAAC;IAC1B,IAAI,GAAtB,OAAO;IACU,WAAW,GAA5B,MAAM;IACW,iBAAiB,GAAlC,MAAM;IACJ;IACZ,IAAQ,EAAE,MAAM,CAAC;IACjB,QAAY,EAAE,OAAO,oDAAoD,EAAE,cAAc,CAAC;IAC1F,KAAS,EAAE;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAC,EAAE,GAAC,IAAI,CAAC;IACpD,eAAmB,EAAE,MAAM,EAAE,CAAC;IAC9B,KAAS,EAAE,MAAM,CAAC;IAClB,IAAQ,EAAE,OAAO,gBAAgB,EAAE,SAAS,GAAC,IAAI,CAAC;IAClD,MAAU,EAAE,OAAO,4CAA4C,EAAE,MAAM,CAAA;CACpE,CA+HH;AAED;;;;;;;GAOG;AACH,4CAJW,OAAO,kDAAkD,EAAE,eAAe,WAC1E,OAAO,+CAA+C,EAAE,sBAAsB,UAC9E,WAAW,iBAAiB,CAAC,QAiBvC;4BAhM2B,8CAA8C"}

package/src/generation/foliage/asset/place_tree.js

@@ -19,7 +19,8 @@ import { generate_tree } from "./generate_tree.js";
  *
  * @param {import("../../../shade/renderer/scene/GPUSceneContext.js").GPUSceneContext} scene_context
  * @param {import("../../../engine/ecs/EntityComponentDataset.js").EntityComponentDataset} dataset
- * @param {Object} [options={}]
+ * @param {Object} [options={}] without a `tree` or a `prefab`, the tree is grown from these by `generate_tree` (its
+ *        `preset`, `seed`, `growth`, `cache` and the rest)
  * @param {import("./TreeAsset.js").TreeAsset} [options.tree] pre-generated `TreeAsset`
  * @param {import("../../../engine/graphics3/prefab/Prefab.js").Prefab} [options.prefab] pre-compiled `Prefab`
  * @param {number} [options.lod=0] LOD index when placing from `TreeAsset`

package/src/generation/foliage/asset/tree_lod_plan.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Triangles a tree drawn to `error` costs: its bark (as `tree_mesh_build_bark` draws it) and a hull for each of its
+ * clusters' cards (`tree_clusters`, `tree_cluster_cards`, `tree_mesh_build_clusters`).
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig} species
+ * @param {import("../mesh/foliage_collect_attachments.js").FoliageAttachmentSet} attachments
+ * @param {number} error m
+ * @returns {number}
+ */
+export function tree_triangles_at_error(skeleton: import("../skeleton/TreeSkeleton.js").TreeSkeleton, species: import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig, attachments: import("../mesh/foliage_collect_attachments.js").FoliageAttachmentSet, error: number): number;
+/**
+ * One LOD of a tree: the error it is drawn to and the rig on the wood it draws.
+ *
+ * @typedef {Object} TreeLODPlan
+ * @property {number} error m
+ * @property {ReturnType<typeof tree_skeleton_assign_skin_joints>} skin_info its wind joints
+ */
+/**
+ * Each LOD's geometric error and rig: the finest error at which the tree fits that LOD's
+ * `TREE_RENDER_COST_CEILING` over `side_area` (`tree_grown_side_area`), its bark and cluster cards in triangles and,
+ * when it is rigged for wind, its joints, no finer than the LOD before it and no finer than `TREE_LOD_ERROR_FINEST`:
+ * each halving of the error quadruples the cluster cards' texels, which no ceiling yet bounds. Errors are tried a
+ * half-octave apart ({@link TREE_LOD_ERROR_STEP}), up from the finest until the tree fits, or until it draws no wood at all.
+ *
+ * An LOD's rig (`tree_skeleton_assign_skin_joints`) is on the wood it draws, at a tolerance no finer than its error
+ * (a sway smaller than the shape's error cannot be seen), and its joints are a subset of the finer LOD's. The
+ * skeleton is left bound to the coarsest; `tree_skeleton_bind_skin_joints` binds another.
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig} species
+ * @param {import("../mesh/foliage_collect_attachments.js").FoliageAttachmentSet} attachments
+ * @param {number} side_area m^2
+ * @param {number} lod_count
+ * @param {Map<number, ReturnType<typeof tree_mesh_compute_branch_rings>>} [planned] the bark's rings the caller has
+ *        already planned (`tree_mesh_compute_branch_rings`), by error: the search takes them rather than planning them
+ *        again
+ * @param {((error: number) => number)|null} [cards] how many cards the tree draws at an error, where they are not its
+ *        own cuts (`tree_shoot_instance_card_count`); its own clusters (`tree_clusters`) by default
+ * @returns {TreeLODPlan[]}
+ */
+export function tree_lod_plan(skeleton: import("../skeleton/TreeSkeleton.js").TreeSkeleton, species: import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig, attachments: import("../mesh/foliage_collect_attachments.js").FoliageAttachmentSet, side_area: number, lod_count: number, planned?: Map<number, Map<number, {
+    cx: number;
+    cy: number;
+    cz: number;
+    r: number;
+    m: number;
+    t_norm: number;
+    flute_amp: number;
+    j0: number;
+    j1: number;
+    j2: number;
+    j3: number;
+    w0: number;
+    w1: number;
+    w2: number;
+    w3: number;
+}[]>>, cards?: ((error: number) => number) | null): TreeLODPlan[];
+/**
+ * One LOD of a tree: the error it is drawn to and the rig on the wood it draws.
+ */
+export type TreeLODPlan = {
+    /**
+     * m
+     */
+    error: number;
+    /**
+     * its wind joints
+     */
+    skin_info: ReturnType<typeof tree_skeleton_assign_skin_joints>;
+};
+import { tree_skeleton_assign_skin_joints } from "../skeleton/tree_skeleton_assign_skin_joints.js";
+//# sourceMappingURL=tree_lod_plan.d.ts.map

package/src/generation/foliage/asset/tree_lod_plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree_lod_plan.d.ts","sourceRoot":"","sources":["../../../../../src/generation/foliage/asset/tree_lod_plan.js"],"names":[],"mappings":"AAiCA;;;;;;;;;GASG;AACH,kDANW,OAAO,6BAA6B,EAAE,YAAY,WAClD,OAAO,gCAAgC,EAAE,iBAAiB,eAC1D,OAAO,wCAAwC,EAAE,oBAAoB,SACrE,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wCAZW,OAAO,6BAA6B,EAAE,YAAY,WAClD,OAAO,gCAAgC,EAAE,iBAAiB,eAC1D,OAAO,wCAAwC,EAAE,oBAAoB,aACrE,MAAM,aACN,MAAM,YACN,IAAI,MAAM;;;;;;;;;;;;;;;;KAAoD,UAG9D,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,GAAC,IAAI,GAE9B,WAAW,EAAE,CAwCzB;;;;;;;;WAjEa,MAAM;;;;eACN,WAAW,uCAAuC,CAAC;;iDA/ChB,iDAAiD"}

package/src/generation/foliage/asset/tree_lod_plan.js

@@ -0,0 +1,117 @@
+import { TREE_RENDER_COST_CEILING } from "../analysis/tree_render_cost.js";
+import { TREE_LOD_ERROR_FINEST, TREE_LOD_ERROR_STEP } from "../config/TreeLODConfig.js";
+import { CUTOUT_HULL_VERTEX_COUNT } from "../material/FoliageAtlasCutout.js";
+import { tree_clusters } from "../mesh/tree_clusters.js";
+import { tree_mesh_compute_branch_rings } from "../mesh/tree_mesh_build_bark.js";
+import { tree_skeleton_assign_skin_joints } from "../skeleton/tree_skeleton_assign_skin_joints.js";
+
+/**
+ * Triangles the bark `rings` and the cluster cards of the wood they leave out cost.
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {import("../mesh/foliage_collect_attachments.js").FoliageAttachmentSet} attachments
+ * @param {Map<number, Array<{m: number}>>} rings
+ * @returns {number}
+ */
+function triangles_of(skeleton, attachments, rings, cards) {
+    let triangles = 0;
+    for (const list of rings.values()) {
+        for (let i = 1; i < list.length; i++) {
+            triangles += list[i - 1].m + list[i].m;
+        }
+        // the tip's cap
+        triangles += list[list.length - 1].m;
+    }
+    if (cards !== null) {
+        triangles += cards(rings) * CUTOUT_HULL_VERTEX_COUNT;
+    } else if (attachments.count > 0 || rings.size < skeleton.branch_count) {
+        // a card per cluster
+        triangles += tree_clusters(skeleton, attachments, rings).length * CUTOUT_HULL_VERTEX_COUNT;
+    }
+    return triangles;
+}
+
+/**
+ * Triangles a tree drawn to `error` costs: its bark (as `tree_mesh_build_bark` draws it) and a hull for each of its
+ * clusters' cards (`tree_clusters`, `tree_cluster_cards`, `tree_mesh_build_clusters`).
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig} species
+ * @param {import("../mesh/foliage_collect_attachments.js").FoliageAttachmentSet} attachments
+ * @param {number} error m
+ * @returns {number}
+ */
+export function tree_triangles_at_error(skeleton, species, attachments, error) {
+    return triangles_of(skeleton, attachments, tree_mesh_compute_branch_rings(skeleton, species, { error }), null);
+}
+
+/**
+ * One LOD of a tree: the error it is drawn to and the rig on the wood it draws.
+ *
+ * @typedef {Object} TreeLODPlan
+ * @property {number} error m
+ * @property {ReturnType<typeof tree_skeleton_assign_skin_joints>} skin_info its wind joints
+ */
+
+/**
+ * Each LOD's geometric error and rig: the finest error at which the tree fits that LOD's
+ * `TREE_RENDER_COST_CEILING` over `side_area` (`tree_grown_side_area`), its bark and cluster cards in triangles and,
+ * when it is rigged for wind, its joints, no finer than the LOD before it and no finer than `TREE_LOD_ERROR_FINEST`:
+ * each halving of the error quadruples the cluster cards' texels, which no ceiling yet bounds. Errors are tried a
+ * half-octave apart ({@link TREE_LOD_ERROR_STEP}), up from the finest until the tree fits, or until it draws no wood at all.
+ *
+ * An LOD's rig (`tree_skeleton_assign_skin_joints`) is on the wood it draws, at a tolerance no finer than its error
+ * (a sway smaller than the shape's error cannot be seen), and its joints are a subset of the finer LOD's. The
+ * skeleton is left bound to the coarsest; `tree_skeleton_bind_skin_joints` binds another.
+ *
+ * @param {import("../skeleton/TreeSkeleton.js").TreeSkeleton} skeleton
+ * @param {import("../config/TreeSpeciesConfig.js").TreeSpeciesConfig} species
+ * @param {import("../mesh/foliage_collect_attachments.js").FoliageAttachmentSet} attachments
+ * @param {number} side_area m^2
+ * @param {number} lod_count
+ * @param {Map<number, ReturnType<typeof tree_mesh_compute_branch_rings>>} [planned] the bark's rings the caller has
+ *        already planned (`tree_mesh_compute_branch_rings`), by error: the search takes them rather than planning them
+ *        again
+ * @param {((error: number) => number)|null} [cards] how many cards the tree draws at an error, where they are not its
+ *        own cuts (`tree_shoot_instance_card_count`); its own clusters (`tree_clusters`) by default
+ * @returns {TreeLODPlan[]}
+ */
+export function tree_lod_plan(skeleton, species, attachments, side_area, lod_count, planned = new Map(), cards = null) {
+    const ceiling = TREE_RENDER_COST_CEILING;
+    const rigged = species.wind.enabled;
+    const drawn = new Map();
+    const at = (error) => {
+        let d = drawn.get(error);
+        if (d === undefined) {
+            const rings = planned.get(error) ?? tree_mesh_compute_branch_rings(skeleton, species, { error });
+            d = { rings, density: triangles_of(skeleton, attachments, rings, cards === null ? null : () => cards(error)) / side_area };
+            drawn.set(error, d);
+        }
+        return d;
+    };
+    /** @type {TreeLODPlan[]} */
+    const plan = [];
+    let error = TREE_LOD_ERROR_FINEST;
+    let finer = null;
+    for (let k = 0; k < lod_count; k++) {
+        const triangle_ceiling = ceiling.triangle_density[Math.min(k, ceiling.triangle_density.length - 1)];
+        for (; ;) {
+            const d = at(error);
+            const last = d.rings.size === 0;
+            if (d.density <= triangle_ceiling || last) {
+                const skin_info = tree_skeleton_assign_skin_joints(skeleton, species, {
+                    tolerance: Math.max(species.wind.deflection_tolerance, error),
+                    rings: d.rings,
+                    within: finer !== null ? finer.joint_vertex_ids : null
+                });
+                if (!rigged || skin_info.joint_count / side_area <= ceiling.joint_density || last) {
+                    plan.push({ error, skin_info });
+                    finer = skin_info;
+                    break;
+                }
+            }
+            error *= TREE_LOD_ERROR_STEP;
+        }
+    }
+    return plan;
+}