@woosh/meep-engine 3.52.0 → 3.54.0

package/src/shade/renderer/light/world_cluster/shader_world_cluster_assign_lights.js

@@ -0,0 +1,163 @@
+import { COLLECTION_U32_STRUCT_READ } from "../../gpu_primitive/COLLECTION_U32_STRUCT_READ.js";
+import { COLLECTION_U32_STRUCT_WRITE } from "../../gpu_primitive/COLLECTION_U32_STRUCT_WRITE.js";
+import { chunk_grid3d_to_index } from "../../shader/chunk/grid/chunk_grid3d_to_index.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { IRRADIANCE_CLIPMAP_TILE_BORDER } from "../../volumetrics/irradiance_clipmap/IRRADIANCE_CLIPMAP.js";
+import { IRRADIANCE_CLIPMAP_STRUCT } from "../../volumetrics/irradiance_clipmap/IRRADIANCE_CLIPMAP_STRUCT.js";
+import { chunk_light_cluster_counts } from "../cluster/chunk_light_cluster_counts.js";
+import { CLUSTER_LIGHT_PROXY } from "../cluster/CLUSTER_LIGHT_PROXY.js";
+import { chunk_cluster_light_tuple } from "../cluster/CLUSTER_LIGHT_TYPE.js";
+import { LIGHT_CLUSTER_METADATA } from "../cluster/LIGHT_CLUSTER_METADATA.js";
+import { LIGHT_CLUSTER_LOOKUP_STRUCT } from "../cluster/shader_cluster_assign_lights.js";
+import {
+    chunk_world_cluster_aabb,
+    WORLD_LIGHT_CLUSTER_GRID_SIZE,
+    WORLD_LIGHT_CLUSTER_MAX_LIGHTS_PER_CELL,
+} from "./WORLD_LIGHT_CLUSTER.js";
+
+export const WORLD_CLUSTER_ASSIGN_WORKGROUP_SIZE = Object.freeze([4, 4, 4]);
+const BATCH_SIZE = 64;
+const MAX_PER_TYPE = WORLD_LIGHT_CLUSTER_MAX_LIGHTS_PER_CELL >>> 1;
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .addUniform("irradiance_clipmap", IRRADIANCE_CLIPMAP_STRUCT)
+    .addStorageBuffer("culled_lights", COLLECTION_U32_STRUCT_READ, false)
+    .addStorageBuffer("proxies", WebGPUArray.from(CLUSTER_LIGHT_PROXY), false)
+    .addStorageBuffer("world_cluster_lookup", LIGHT_CLUSTER_LOOKUP_STRUCT, true)
+    .addStorageBuffer("world_cluster_data", COLLECTION_U32_STRUCT_WRITE, true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+const GRID_SIZE: u32 = ${WORLD_LIGHT_CLUSTER_GRID_SIZE}u;
+const BATCH_SIZE: u32 = ${BATCH_SIZE}u;
+const MAX_PER_TYPE: u32 = ${MAX_PER_TYPE}u;
+const BORDER: f32 = ${IRRADIANCE_CLIPMAP_TILE_BORDER}.0;
+
+var<workgroup> shared_tuples: array<u32, ${BATCH_SIZE}>;
+var<workgroup> shared_proxies: array<${CLUSTER_LIGHT_PROXY.wgsl_ref}, ${BATCH_SIZE}>;
+
+@compute @workgroup_size(4, 4, 4)
+fn main(
+    @builtin(global_invocation_id) global_id: vec3<u32>,
+    @builtin(local_invocation_index) local_index: u32,
+) {
+    let cascade = global_id.z / GRID_SIZE;
+    let cell = vec3<u32>(global_id.x, global_id.y, global_id.z % GRID_SIZE);
+    let valid_cell = cascade < irradiance_clipmap.cascade_count && all(cell < vec3<u32>(GRID_SIZE));
+
+    var cell_lo = vec3<f32>(0.0);
+    var cell_hi = vec3<f32>(0.0);
+
+    if (valid_cell) {
+        let level = irradiance_clipmap.levels[cascade];
+        let box_min = (vec3<f32>(level.corner) - vec3<f32>(BORDER)) * level.cell_size;
+        let cluster_cell_size = (vec3<f32>(level.size) + vec3<f32>(2.0 * BORDER)) * (level.cell_size / f32(GRID_SIZE));
+        let base_lo = box_min + vec3<f32>(cell) * cluster_cell_size;
+        let half_voxel = vec3<f32>(0.5 * level.cell_size);
+        cell_lo = base_lo - half_voxel;
+        cell_hi = base_lo + cluster_cell_size + half_voxel;
+    }
+
+    var point_ids: array<u32, ${MAX_PER_TYPE}>;
+    var spot_ids: array<u32, ${MAX_PER_TYPE}>;
+    var point_count = 0u;
+    var spot_count = 0u;
+
+    let total_lights = min(culled_lights.count, u32(arrayLength(&proxies)));
+
+    for (var base = 0u; base < total_lights; base += BATCH_SIZE) {
+        let idx = base + local_index;
+        if (idx < total_lights) {
+            shared_tuples[local_index] = culled_lights.elements[idx];
+            shared_proxies[local_index] = proxies[idx];
+        }
+        workgroupBarrier();
+
+        if (valid_cell) {
+            let batch_count = min(BATCH_SIZE, total_lights - base);
+            for (var i = 0u; i < batch_count; i++) {
+                let tuple = shared_tuples[i];
+                let proxy = shared_proxies[i];
+                let light_type = cluster_light_tuple_type(tuple);
+                let light_id = cluster_light_tuple_id(tuple);
+
+                if (light_type == CLUSTER_LIGHT_TYPE_POINT) {
+                    if (point_count < MAX_PER_TYPE) {
+                        if (proxy.unbounded != 0u || world_cluster_sphere_intersects_aabb(proxy.bound.xyz, proxy.bound.w, cell_lo, cell_hi)) {
+                            point_ids[point_count] = light_id;
+                            point_count++;
+                        }
+                    }
+                } else {
+                    if (spot_count < MAX_PER_TYPE) {
+                        if (proxy.unbounded != 0u || world_cluster_cone_intersects_aabb(proxy, cell_lo, cell_hi)) {
+                            spot_ids[spot_count] = light_id;
+                            spot_count++;
+                        }
+                    }
+                }
+            }
+        }
+
+        workgroupBarrier();
+    }
+
+    if (!valid_cell) {
+        return;
+    }
+
+    let cluster_index = grid3d_to_index(vec3<u32>(cell.xy, cascade * GRID_SIZE + cell.z), vec2<u32>(GRID_SIZE));
+    let total_assigned = point_count + spot_count;
+    var offset = 0u;
+
+    if (total_assigned > 0u) {
+        let capacity = u32(arrayLength(&world_cluster_data.elements));
+        let raw_offset = atomicAdd(&world_cluster_data.count, total_assigned);
+        if (raw_offset + total_assigned <= capacity) {
+            offset = raw_offset;
+            for (var p = 0u; p < point_count; p++) {
+                world_cluster_data.elements[offset + p] = point_ids[p];
+            }
+            for (var s = 0u; s < spot_count; s++) {
+                world_cluster_data.elements[offset + point_count + s] = spot_ids[s];
+            }
+        } else {
+            point_count = 0u;
+            spot_count = 0u;
+        }
+    }
+
+    world_cluster_lookup[cluster_index] = ${LIGHT_CLUSTER_METADATA.make({
+        // +4u because COLLECTION_U32_STRUCT_WRITE aligns `elements` to 16 bytes (4 u32 words)
+        offset: "offset + 4u",
+        counts: "light_cluster_pack_counts(point_count, spot_count)",
+    })};
+}
+`, [
+        IRRADIANCE_CLIPMAP_STRUCT.declaration_chunk,
+        CLUSTER_LIGHT_PROXY.declaration_chunk,
+        LIGHT_CLUSTER_METADATA.declaration_chunk,
+        chunk_grid3d_to_index,
+        chunk_world_cluster_aabb,
+        chunk_cluster_light_tuple,
+        chunk_light_cluster_counts,
+    ]
+);
+
+/**
+ * Assigns world-space culled point and spot lights to the `8 × 8 × 8` cluster cells of each
+ * cascade of the world-space irradiance clipmap.
+ *
+ * @type {ComputeShader}
+ */
+export const shader_world_cluster_assign_lights = ComputeShader.from({
+    label: "World cluster / assign lights",
+    resources,
+    body,
+});

package/src/shade/renderer/light/world_cluster/shader_world_cluster_cull_lights.d.ts

@@ -0,0 +1,4 @@
+export const shader_world_cluster_cull_point_lights: ComputeShader;
+export const shader_world_cluster_cull_spot_lights: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_world_cluster_cull_lights.d.ts.map

package/src/shade/renderer/light/world_cluster/shader_world_cluster_cull_lights.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_world_cluster_cull_lights.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/light/world_cluster/shader_world_cluster_cull_lights.js"],"names":[],"mappings":"AAwHA,mEAOG;AAEH,kEAOG;8BAtI2B,+BAA+B"}

package/src/shade/renderer/light/world_cluster/shader_world_cluster_cull_lights.js

@@ -0,0 +1,137 @@
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { COMPUTE_SHADER_DEFAULT_GROUP_SIZE } from "../../shader/COMPUTE_SHADER_DEFAULT_GROUP_SIZE.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { WebGPUArray } from "../../shader/type/WebGPUArray.js";
+import { chunk_point_lights_iterate } from "../../shader/chunk/light/io/chunk_point_lights_iterate.js";
+import { chunk_spot_lights_iterate } from "../../shader/chunk/light/io/chunk_spot_lights_iterate.js";
+import { SUBGROUP_APPEND_NONE } from "../../shader/chunk/subgroup/chunk_subgroup_append_slot.js";
+import { LIGHT_DATABASE_SPEC } from "../LIGHT_DATABASE_SPEC.js";
+import { chunk_collection_u32_append } from "../../gpu_primitive/chunk_collection_u32_append.js";
+import { COLLECTION_U32_STRUCT_WRITE } from "../../gpu_primitive/COLLECTION_U32_STRUCT_WRITE.js";
+import { chunk_cluster_light_proxy } from "../cluster/chunk_cluster_light_proxy.js";
+import { CLUSTER_LIGHT_PROXY, CLUSTER_LIGHT_PROXY_UNBOUNDED_RADIUS } from "../cluster/CLUSTER_LIGHT_PROXY.js";
+import { CLUSTER_LIGHT_TYPE, chunk_cluster_light_tuple } from "../cluster/CLUSTER_LIGHT_TYPE.js";
+import { chunk_world_cluster_aabb, WORLD_LIGHT_CLUSTER_CULL_SETTINGS } from "./WORLD_LIGHT_CLUSTER.js";
+
+const POINT_DESCRIPTOR = LIGHT_DATABASE_SPEC.get("light_point");
+const SPOT_DESCRIPTOR = LIGHT_DATABASE_SPEC.get("light_spot");
+
+const WORKGROUP_SIZE = COMPUTE_SHADER_DEFAULT_GROUP_SIZE;
+
+function build_world_cull_shader({
+    label,
+    prefix_upper,
+    prefix_lower,
+    iterate_chunk,
+    read_chunk,
+    is_spot,
+}) {
+    const resources = new ShaderResourceSetDescriptor();
+
+    resources.createGroup()
+        .addUniform("settings", WORLD_LIGHT_CLUSTER_CULL_SETTINGS)
+        .addStorageBuffer("light_data", WebGPUArray.u32, false)
+        .addStorageBuffer("output_list", COLLECTION_U32_STRUCT_WRITE, true)
+        .addStorageBuffer("proxies", WebGPUArray.from(CLUSTER_LIGHT_PROXY), true);
+
+    const build_proxy_wgsl = is_spot
+        ? /* language=WGSL */ `
+                let light = ${SPOT_DESCRIPTOR.marshalling_method_read}(&light_data, light_index);
+                let apex = light.position;
+                let direction = normalize(light.direction);
+                let height = light.distance + light.radius;
+                proxy.apex_height = vec4<f32>(apex, height);
+                proxy.direction_cos = vec4<f32>(direction, light.coneCos);
+                proxy.source_radius = light.radius;
+                if (light.distance <= 0.0) {
+                    proxy.unbounded = 1u;
+                    proxy.bound = vec4<f32>(apex, ${CLUSTER_LIGHT_PROXY_UNBOUNDED_RADIUS.toExponential()});
+                } else {
+                    proxy.bound = cluster_spot_bound(apex, direction, height, light.coneCos, light.radius);
+                }
+                want = proxy.unbounded != 0u || world_cluster_cone_intersects_aabb(proxy, settings.coarsest_min, settings.coarsest_max);
+`
+        : /* language=WGSL */ `
+                let light = ${POINT_DESCRIPTOR.marshalling_method_read}(&light_data, light_index);
+                let radius = select(light.radius + light.distance, ${CLUSTER_LIGHT_PROXY_UNBOUNDED_RADIUS.toExponential()}, light.distance <= 0.0);
+                proxy.unbounded = select(0u, 1u, light.distance <= 0.0);
+                proxy.bound = vec4<f32>(light.position, radius);
+                proxy.source_radius = light.radius;
+                want = proxy.unbounded != 0u || world_cluster_sphere_intersects_aabb(proxy.bound.xyz, proxy.bound.w, settings.coarsest_min, settings.coarsest_max);
+`;
+
+    const cluster_type = is_spot ? CLUSTER_LIGHT_TYPE.Spot : CLUSTER_LIGHT_TYPE.Point;
+
+    const body = CodeChunk.from(
+        //language=WGSL
+        `
+@compute @workgroup_size(${WORKGROUP_SIZE}, 1, 1)
+fn main(@builtin(global_invocation_id) global_id: vec3<u32>) {
+    if (settings.cascade_count == 0u) {
+        return;
+    }
+
+    let id = global_id.x;
+    let page_index = id / ${prefix_upper}_ELEMENTS_PER_PAGE;
+    let in_page_slot = id % ${prefix_upper}_ELEMENTS_PER_PAGE;
+
+    var want = false;
+    var light_index = 0u;
+    var proxy: ${CLUSTER_LIGHT_PROXY.wgsl_ref};
+
+    if (page_index < ${prefix_upper}_PAGE_LIMIT) {
+        let page_address = ${prefix_lower}_page_address(&light_data, page_index);
+        if (page_address != ~0u) {
+            let word_index = in_page_slot >> 5u;
+            let bit = in_page_slot & 31u;
+            let bitmap_word = ${prefix_lower}_page_bitmap_word(&light_data, page_address, word_index);
+            if ((bitmap_word & (1u << bit)) != 0u) {
+                light_index = ${prefix_lower}_slot_to_index(page_index, in_page_slot);
+${build_proxy_wgsl}
+            }
+        }
+    }
+
+    let capacity = min(u32(arrayLength(&output_list.elements)), u32(arrayLength(&proxies)));
+    let tuple = cluster_light_tuple_pack(light_index, ${cluster_type}u);
+    let slot = collection_u32_append(&output_list, want, tuple, capacity);
+    if (slot != ${SUBGROUP_APPEND_NONE}u) {
+        proxies[slot] = proxy;
+    }
+}
+`, [
+        CLUSTER_LIGHT_PROXY.declaration_chunk,
+        chunk_cluster_light_proxy,
+        chunk_world_cluster_aabb,
+        chunk_cluster_light_tuple,
+        chunk_collection_u32_append,
+        iterate_chunk,
+        read_chunk,
+        ]
+    );
+
+    return ComputeShader.from({
+        label,
+        resources,
+        body,
+    });
+}
+
+export const shader_world_cluster_cull_point_lights = build_world_cull_shader({
+    label: "World cluster / cull point lights",
+    prefix_upper: "POINT_LIGHTS",
+    prefix_lower: "point_lights",
+    iterate_chunk: chunk_point_lights_iterate,
+    read_chunk: POINT_DESCRIPTOR.chunk_read,
+    is_spot: false,
+});
+
+export const shader_world_cluster_cull_spot_lights = build_world_cull_shader({
+    label: "World cluster / cull spot lights",
+    prefix_upper: "SPOT_LIGHTS",
+    prefix_lower: "spot_lights",
+    iterate_chunk: chunk_spot_lights_iterate,
+    read_chunk: SPOT_DESCRIPTOR.chunk_read,
+    is_spot: true,
+});

package/src/shade/renderer/loader/SceneBundle.d.ts

@@ -39,6 +39,13 @@ export class SceneBundle {
      * @type {ShadeAnimationClip[]}
      */
     clips: ShadeAnimationClip[];
+    /**
+     * Aeroelastic foliage wind rigs extracted from or generated for the asset.
+     * Each rig's `root` and each joint's `target` is an index into {@link nodes}.
+     *
+     * @type {import("../animation/foliage/FoliageWindRig.js").FoliageWindRig[]}
+     */
+    foliage_rigs: import("../animation/foliage/FoliageWindRig.js").FoliageWindRig[];
     /**
      * Punctual lights extracted from the asset, each with the index of the node it sits on. A
      * light is not a node and has no place of its own; the node's transform is where it is,

package/src/shade/renderer/loader/SceneBundle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SceneBundle.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/loader/SceneBundle.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AAEH;;;;;;;;;;;;;GAaG;AACH;IACI;;;;OAIG;IACH,OAFU,SAAS,EAAE,CAEV;IAEX;;;;;OAKG;IACH,OAFU,IAAI,EAAE,CAEL;IAEX;;;;;OAKG;IACH,OAFU,kBAAkB,EAAE,CAEnB;IAEX;;;;;;OAMG;IACH,QAFU;QAAC,KAAK,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,EAAE,CAE5B;IAEZ;;;;;;OAMG;IACH,eAHW,SAAS,GACP,MAAM,CAalB;IAED;;;;;OAKG;IACH,0BAFa,YAAY,EAAE,CAsB1B;IAGL;;;OAGG;IACH,wBAFU,OAAO,CAEkB;CANlC;wBApGY,OAAO,gBAAgB,EAAE,SAAS;mBAClC,OAAO,sBAAsB,EAAE,IAAI;iCACnC,OAAO,oCAAoC,EAAE,kBAAkB;oBAC/D,OAAO,yBAAyB,EAAE,KAAK"}
+{"version":3,"file":"SceneBundle.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/loader/SceneBundle.js"],"names":[],"mappings":"AAGA;;;;;GAKG;AAEH;;;;;;;;;;;;;GAaG;AACH;IACI;;;;OAIG;IACH,OAFU,SAAS,EAAE,CAEV;IAEX;;;;;OAKG;IACH,OAFU,IAAI,EAAE,CAEL;IAEX;;;;;OAKG;IACH,OAFU,kBAAkB,EAAE,CAEnB;IAEX;;;;;OAKG;IACH,cAFU,OAAO,wCAAwC,EAAE,cAAc,EAAE,CAEzD;IAElB;;;;;;OAMG;IACH,QAFU;QAAC,KAAK,EAAE,KAAK,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,EAAE,CAE5B;IAEZ;;;;;;OAMG;IACH,eAHW,SAAS,GACP,MAAM,CAalB;IAED;;;;;OAKG;IACH,0BAFa,YAAY,EAAE,CAsB1B;IAGL;;;OAGG;IACH,wBAFU,OAAO,CAEkB;CANlC;wBA5GY,OAAO,gBAAgB,EAAE,SAAS;mBAClC,OAAO,sBAAsB,EAAE,IAAI;iCACnC,OAAO,oCAAoC,EAAE,kBAAkB;oBAC/D,OAAO,yBAAyB,EAAE,KAAK"}

package/src/shade/renderer/loader/SceneBundle.js

@@ -1,111 +1,119 @@
-import { assert } from "../../../core/assert.js";
-import { m4_multiply } from "../../../core/geom/3d/mat4/m4_multiply.js";
-
-/**
- * @typedef {import("./SceneNode.js").SceneNode} SceneNode
- * @typedef {import("../animation/Skin.js").Skin} Skin
- * @typedef {import("../animation/ShadeAnimationClip.js").ShadeAnimationClip} ShadeAnimationClip
- * @typedef {import("../light/model/Light.js").Light} Light
- */
-
-/**
- * What came out of a loader: a model as a flat list of {@link SceneNode}s in pre-order, with the
- * skins, clips and lights the same file carried, each addressing nodes by index.
- *
- * Not glTF-specific by design — the bundle describes "what a loader produced", not "what was in
- * a file", and every loader ({@link load_gltf}, {@link load_usd}, {@link deserialize_scene})
- * produces one. It is pure data with no lifecycle: a model compiles from it once into a
- * {@link Prefab} (`prefab_compile`), and a prefab is what gets placed — as entities, each holding
- * a row — however many times the model appears. The bundle is read by that compile and never
- * written, so one bundle is shared by every placement, which is what the asset manager hands out.
- *
- * Pre-order is the one structural promise: a node's parent has a lower index. {@link add_node}
- * refuses anything else, so a reader composes world transforms in a single forward pass.
- */
-export class SceneBundle {
-    /**
-     * Every node of the model, parents before children.
-     *
-     * @type {SceneNode[]}
-     */
-    nodes = [];
-
-    /**
-     * Skins extracted from the asset. A skin's `joints` and `meshes` are indices into
-     * {@link nodes}. Empty if the asset has no skinned meshes.
-     *
-     * @type {Skin[]}
-     */
-    skins = [];
-
-    /**
-     * Animation clips extracted from the asset. Each channel's `target` is an index into
-     * {@link nodes}. Empty if the asset has no animations.
-     *
-     * @type {ShadeAnimationClip[]}
-     */
-    clips = [];
-
-    /**
-     * Punctual lights extracted from the asset, each with the index of the node it sits on. A
-     * light is not a node and has no place of its own; the node's transform is where it is,
-     * already turned to shine along the engine's +Z. Empty if the asset has no lights.
-     *
-     * @type {{light: Light, node: number}[]}
-     */
-    lights = [];
-
-    /**
-     * Append a node. Its parent, if it has one, must already be in the bundle — which is what
-     * keeps the list in pre-order.
-     *
-     * @param {SceneNode} node
-     * @returns {number} the node's index, what a child, a skin, a clip or a light names it by
-     */
-    add_node(node) {
-        assert.defined(node, 'node');
-        assert.equal(node.isSceneNode, true, 'node.isSceneNode !== true');
-
-        const index = this.nodes.length;
-
-        assert.lessThan(node.parent, index, `node ${index} (${node.name}) names parent ${node.parent}, which is not in the bundle yet — add parents before children`);
-
-        this.nodes.push(node);
-
-        return index;
-    }
-
-    /**
-     * The world matrix of every node, composed root-first in double precision — what a reader
-     * that wants where things are in the model's own space asks for, once.
-     *
-     * @returns {Float64Array[]} one 4x4 per node, column-major
-     */
-    compute_world_matrices() {
-        const nodes = this.nodes;
-        const count = nodes.length;
-        const worlds = new Array(count);
-
-        for (let i = 0; i < count; i++) {
-            const node = nodes[i];
-            const world = new Float64Array(16);
-            const local = node.local.matrix;
-
-            if (node.parent === -1) {
-                world.set(local);
-            } else {
-                m4_multiply(world, worlds[node.parent], local);
-            }
-
-            worlds[i] = world;
-        }
-
-        return worlds;
-    }
-}
-
-/**
- * @readonly
- * @type {boolean}
- */
-SceneBundle.prototype.isSceneBundle = true;
+import { assert } from "../../../core/assert.js";
+import { m4_multiply } from "../../../core/geom/3d/mat4/m4_multiply.js";
+
+/**
+ * @typedef {import("./SceneNode.js").SceneNode} SceneNode
+ * @typedef {import("../animation/Skin.js").Skin} Skin
+ * @typedef {import("../animation/ShadeAnimationClip.js").ShadeAnimationClip} ShadeAnimationClip
+ * @typedef {import("../light/model/Light.js").Light} Light
+ */
+
+/**
+ * What came out of a loader: a model as a flat list of {@link SceneNode}s in pre-order, with the
+ * skins, clips and lights the same file carried, each addressing nodes by index.
+ *
+ * Not glTF-specific by design — the bundle describes "what a loader produced", not "what was in
+ * a file", and every loader ({@link load_gltf}, {@link load_usd}, {@link deserialize_scene})
+ * produces one. It is pure data with no lifecycle: a model compiles from it once into a
+ * {@link Prefab} (`prefab_compile`), and a prefab is what gets placed — as entities, each holding
+ * a row — however many times the model appears. The bundle is read by that compile and never
+ * written, so one bundle is shared by every placement, which is what the asset manager hands out.
+ *
+ * Pre-order is the one structural promise: a node's parent has a lower index. {@link add_node}
+ * refuses anything else, so a reader composes world transforms in a single forward pass.
+ */
+export class SceneBundle {
+    /**
+     * Every node of the model, parents before children.
+     *
+     * @type {SceneNode[]}
+     */
+    nodes = [];
+
+    /**
+     * Skins extracted from the asset. A skin's `joints` and `meshes` are indices into
+     * {@link nodes}. Empty if the asset has no skinned meshes.
+     *
+     * @type {Skin[]}
+     */
+    skins = [];
+
+    /**
+     * Animation clips extracted from the asset. Each channel's `target` is an index into
+     * {@link nodes}. Empty if the asset has no animations.
+     *
+     * @type {ShadeAnimationClip[]}
+     */
+    clips = [];
+
+    /**
+     * Aeroelastic foliage wind rigs extracted from or generated for the asset.
+     * Each rig's `root` and each joint's `target` is an index into {@link nodes}.
+     *
+     * @type {import("../animation/foliage/FoliageWindRig.js").FoliageWindRig[]}
+     */
+    foliage_rigs = [];
+
+    /**
+     * Punctual lights extracted from the asset, each with the index of the node it sits on. A
+     * light is not a node and has no place of its own; the node's transform is where it is,
+     * already turned to shine along the engine's +Z. Empty if the asset has no lights.
+     *
+     * @type {{light: Light, node: number}[]}
+     */
+    lights = [];
+
+    /**
+     * Append a node. Its parent, if it has one, must already be in the bundle — which is what
+     * keeps the list in pre-order.
+     *
+     * @param {SceneNode} node
+     * @returns {number} the node's index, what a child, a skin, a clip or a light names it by
+     */
+    add_node(node) {
+        assert.defined(node, 'node');
+        assert.equal(node.isSceneNode, true, 'node.isSceneNode !== true');
+
+        const index = this.nodes.length;
+
+        assert.lessThan(node.parent, index, `node ${index} (${node.name}) names parent ${node.parent}, which is not in the bundle yet — add parents before children`);
+
+        this.nodes.push(node);
+
+        return index;
+    }
+
+    /**
+     * The world matrix of every node, composed root-first in double precision — what a reader
+     * that wants where things are in the model's own space asks for, once.
+     *
+     * @returns {Float64Array[]} one 4x4 per node, column-major
+     */
+    compute_world_matrices() {
+        const nodes = this.nodes;
+        const count = nodes.length;
+        const worlds = new Array(count);
+
+        for (let i = 0; i < count; i++) {
+            const node = nodes[i];
+            const world = new Float64Array(16);
+            const local = node.local.matrix;
+
+            if (node.parent === -1) {
+                world.set(local);
+            } else {
+                m4_multiply(world, worlds[node.parent], local);
+            }
+
+            worlds[i] = world;
+        }
+
+        return worlds;
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+SceneBundle.prototype.isSceneBundle = true;

package/src/shade/renderer/loader/gltf/tiny-gltf.d.ts

@@ -13,7 +13,7 @@ export class TinyGltf {
      * @readonly
      * @type {TextureFormat}
      */
-    static readonly "__#287@#UNCOMPRESSED_TARGET": TextureFormat;
+    static readonly "__#289@#UNCOMPRESSED_TARGET": TextureFormat;
     /**
      * @param {AssetManager} assetManager
      * @param {AssetRequestScope} [scope]

package/src/shade/renderer/material/standard/fragment_gbuffer.d.ts

@@ -45,6 +45,10 @@ export function build_gbuffer_pipeline_descriptor({ label, material_group, surfa
  * @returns {RenderPipelineDescriptor}
  */
 export function gbuffer_pipeline_descriptor_for_shader(label: string, shader: ShaderDescriptor): RenderPipelineDescriptor;
+/**
+ *
+ * @type {number}
+ */
 /**
  * Group 1 of every material's G-buffer pipeline: the visibility buffer and the view that drew it.
  *

package/src/shade/renderer/material/standard/fragment_gbuffer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fragment_gbuffer.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/material/standard/fragment_gbuffer.js"],"names":[],"mappings":"AAkGA;;;;;;;;GAQG;AACH,+DAHW,6BAA6B,GAC3B,2BAA2B,CAUvC;AASD;;;;;;;;;;;GAWG;AACH,qDAHW,SAAS,GACP,SAAS,CA8OrB;AAED;;;;;;;;;GASG;AACH;IAL2B,KAAK,EAArB,MAAM;IACiC,cAAc,EAArD,6BAA6B;IACV,OAAO,EAA1B,SAAS;IACP,wBAAwB,CAUpC;AAED;;;;;;;GAOG;AACH,8DAJW,MAAM,UACN,gBAAgB,GACd,wBAAwB,CA4BpC;AAnXD;;;;;;;;;GASG;AACH,qCAFU,6BAA6B,CAEmC;AAa1E;;;;GAIG;AACH,uCAFU,6BAA6B,CAEqC;AAgC5E;;;;GAIG;AACH,wCAFU,2BAA2B,CAEoE;AAoTzG;;;;GAIG;AACH,6BAFU,gBAAgB,CAMvB;8CA7Y2C,wDAAwD;4CAC1D,sDAAsD;0BAFxE,oCAAoC;yCAxCrB,iEAAiE;iCA2CzE,kCAAkC"}
+{"version":3,"file":"fragment_gbuffer.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/material/standard/fragment_gbuffer.js"],"names":[],"mappings":"AAkGA;;;;;;;;GAQG;AACH,+DAHW,6BAA6B,GAC3B,2BAA2B,CAUvC;AASD;;;;;;;;;;;GAWG;AACH,qDAHW,SAAS,GACP,SAAS,CA+OrB;AAED;;;;;;;;;GASG;AACH;IAL2B,KAAK,EAArB,MAAM;IACiC,cAAc,EAArD,6BAA6B;IACV,OAAO,EAA1B,SAAS;IACP,wBAAwB,CAUpC;AAED;;;;;;;GAOG;AACH,8DAJW,MAAM,UACN,gBAAgB,GACd,wBAAwB,CA4BpC;AA1XD;;;GAGG;AAGH;;;;;;;;;GASG;AACH,qCAFU,6BAA6B,CAEmC;AAa1E;;;;GAIG;AACH,uCAFU,6BAA6B,CAEqC;AAgC5E;;;;GAIG;AACH,wCAFU,2BAA2B,CAEoE;AAqTzG;;;;GAIG;AACH,6BAFU,gBAAgB,CAMvB;8CA9Y2C,wDAAwD;4CAC1D,sDAAsD;0BAFxE,oCAAoC;yCAxCrB,iEAAiE;iCA2CzE,kCAAkC"}

package/src/shade/renderer/material/standard/fragment_gbuffer.js

@@ -9,7 +9,7 @@ import { GEOMETRY_METADATA_STRUCT } from "../../geometry/GEOMETRY_METADATA_STRUC
 import { MESHLET_METADATA_STRUCT } from "../../geometry/meshlet/encoding/MESHLET_METADATA_STRUCT.js";
 import { chunk_node3d_flags } from "../../scene/chunk_node3d_flags.js";
 import { chunk_scene_database_access } from "../../scene/chunk_scene_database_access.js";
-import { RENDER_GLOBAL_MIP_BIAS } from "../../postprocess/taa/RENDER_GLOBAL_MIP_BIAS.js";
+import { chunk_view_mip_bias } from "../../view/chunk_view_mip_bias.js";
 import { chunk_barycentric_full } from "../../shader/chunk/geometry/triangle/chunk_barycentric_full.js";
 import { chunk_barycentric_interpolate_uv } from "../../shader/chunk/geometry/triangle/chunk_barycentric_interpolate_uv.js";
 import { chunk_compute_normal_matrix_from_m4 } from "../../shader/chunk/geometry/mat4/chunk_compute_normal_matrix_from_m4.js";
@@ -53,7 +53,7 @@ import { SHADING_MATERIAL_RESOURCE_GROUP } from "./SHADING_MATERIAL_RESOURCE_GRO
  *
  * @type {number}
  */
-const MIP_DERIVATIVE_BIAS = 1 / (1 - RENDER_GLOBAL_MIP_BIAS);
+
 
 /**
  * Group 1 of every material's G-buffer pipeline: the visibility buffer and the view that drew it.
@@ -146,7 +146,7 @@ struct GBufferOutput {
 }
 
 // this is a multiplies applies to gradients before invoking texture sampling
-const MIP_BIAS = ${MIP_DERIVATIVE_BIAS.toFixed(8)};
+
 
 @fragment
 fn main(
@@ -228,7 +228,7 @@ fn main(
     var uv_info = barycentric_interpolate_uv(barycentric, geometry_vertex_uv_0, geometry_vertex_uv_1, geometry_vertex_uv_2);
 
     // figure out final mip bias
-    let uv_derivative_bias = MIP_BIAS / view.upscale_ratio;
+    let uv_derivative_bias = view_uv_derivative_bias(view.upscale_ratio);
 
     // bias UV derivatives to supersample textures
     uv_info.ddx *= uv_derivative_bias.x;
@@ -367,7 +367,8 @@ fn main(
         chunk_rgbe9995_encode,
         chunk_dither_color_8bit_triangle_noise,
         chunk_scene_database_access,
-        chunk_node3d_flags,
+        chunk_node3d_flags,
+        chunk_view_mip_bias,
     ]
     );
 }