@woosh/meep-engine 3.60.3 → 3.60.5

package/src/shade/renderer/geometry/sdf/cards/mesh_cards_raster_pass_descriptor.js

@@ -216,8 +216,8 @@ const vertex_code = ShaderDescriptor.from({
 
 /*
  The template is handed what the G-buffer pass hands it, in the geometry's local space, the card
- being there: real derivatives, as this is a raster with neighbours of its own triangle, unbiased, as
- UE's card capture leaves its material mip bias at 0. Both functions run first, in uniform control
+ being there: real derivatives, as this is a raster with neighbours of its own triangle, unbiased (mip
+ bias at 0). Both functions run first, in uniform control
  flow, so a template may sample with implicit derivatives.
 
  Coverage is drawn as the trace draws it, a texel's surface opaque with probability its opacity, from

package/src/shade/renderer/geometry/sdf/cards/shader_mesh_cards_histogram.d.ts

@@ -7,7 +7,7 @@ export const MESH_CARDS_HISTOGRAM_SETTINGS: WebGPUStruct;
  * six directions, over a resident geometry's level-0 occupancy — a brick is occupied when its entry
  * holds a slot. Walking its column along the direction, a thread finds every run start: an occupied
  * brick at layer z whose predecessor is empty or outside the grid. A run start's m is the layer after
- * the previous run's end, or 0 for the first: UE's MinRayZ. The thread counts each run start into
+ * the previous run's end, or 0 for the first. The thread counts each run start into
  * its direction's histogram by (m, z), which the layout's scratch holds cleared.
  *
  * @type {ComputeShader}

package/src/shade/renderer/geometry/sdf/cards/shader_mesh_cards_histogram.js

@@ -31,7 +31,7 @@ resources.createGroup()
  * six directions, over a resident geometry's level-0 occupancy — a brick is occupied when its entry
  * holds a slot. Walking its column along the direction, a thread finds every run start: an occupied
  * brick at layer z whose predecessor is empty or outside the grid. A run start's m is the layer after
- * the previous run's end, or 0 for the first: UE's MinRayZ. The thread counts each run start into
+ * the previous run's end, or 0 for the first. The thread counts each run start into
  * its direction's histogram by (m, z), which the layout's scratch holds cleared.
  *
  * @type {ComputeShader}

package/src/shade/renderer/geometry/sdf/chunk_blas_query_band_sdf.d.ts

@@ -10,8 +10,7 @@ export const BLAS_BAND_VOTE_STRATA: number;
  */
 export const BLAS_BAND_VOTE_RAYS: number;
 /**
- * A geometry's signed distance within a band, signed by UE 5.4's vote (`MeshDistanceFieldUtilities.cpp`,
- * `FMeshDistanceFieldAsyncTask::DoWork`):
+ * A geometry's signed distance within a band, signed by a hemisphere ray vote:
  *
  * - The nearest point within the band, through the BLAS. With none, the point is a band away, outside,
  *   and casts no ray.
@@ -20,9 +19,9 @@ export const BLAS_BAND_VOTE_RAYS: number;
  *   than a quarter of them meet a back face.
  * - A two-sided geometry has no back face: it is outside throughout, and casts no ray either.
  *
- * The directions are UE's, made as its stream runs, ray after ray: `FRandomStream(0)` drives two
- * `GenerateStratifiedUniformHemisphereSamples(49)` on Shirley and Chiu's concentric map, and the second
- * hemisphere's Z is negated. UE's Z is our Y.
+ * The directions are made as the LCG stream runs, ray after ray: a seed of 0 drives two
+ * 49-sample stratified uniform hemisphere sets on Shirley and Chiu's concentric map, and the second
+ * hemisphere's pole is negated (+Y and -Y hemispheres).
  *
  * ```wgsl
  * fn blas_query_band_sdf(point: vec3<f32>, geometry_index: u32, band: f32, two_sided: bool, contact, stack, stack_top: u32) -> f32

package/src/shade/renderer/geometry/sdf/chunk_blas_query_band_sdf.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk_blas_query_band_sdf.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/sdf/chunk_blas_query_band_sdf.js"],"names":[],"mappings":"AAgBA;;;;GAIG;AACH,oCAFU,MAAM,CAEuB;AAEvC;;;GAGG;AACH,kCAFU,MAAM,CAEqE;AAErF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wCAFU,SAAS,CAgHjB;0BAlJwB,oCAAoC"}
+{"version":3,"file":"chunk_blas_query_band_sdf.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/sdf/chunk_blas_query_band_sdf.js"],"names":[],"mappings":"AAgBA;;;;GAIG;AACH,oCAFU,MAAM,CAEuB;AAEvC;;;GAGG;AACH,kCAFU,MAAM,CAEqE;AAErF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wCAFU,SAAS,CAgHjB;0BAjJwB,oCAAoC"}

package/src/shade/renderer/geometry/sdf/chunk_blas_query_band_sdf.js

@@ -28,8 +28,7 @@ export const BLAS_BAND_VOTE_STRATA = 7;
 export const BLAS_BAND_VOTE_RAYS = 2 * BLAS_BAND_VOTE_STRATA * BLAS_BAND_VOTE_STRATA;
 
 /**
- * A geometry's signed distance within a band, signed by UE 5.4's vote (`MeshDistanceFieldUtilities.cpp`,
- * `FMeshDistanceFieldAsyncTask::DoWork`):
+ * A geometry's signed distance within a band, signed by a hemisphere ray vote:
  *
  * - The nearest point within the band, through the BLAS. With none, the point is a band away, outside,
  *   and casts no ray.
@@ -38,9 +37,9 @@ export const BLAS_BAND_VOTE_RAYS = 2 * BLAS_BAND_VOTE_STRATA * BLAS_BAND_VOTE_ST
  *   than a quarter of them meet a back face.
  * - A two-sided geometry has no back face: it is outside throughout, and casts no ray either.
  *
- * The directions are UE's, made as its stream runs, ray after ray: `FRandomStream(0)` drives two
- * `GenerateStratifiedUniformHemisphereSamples(49)` on Shirley and Chiu's concentric map, and the second
- * hemisphere's Z is negated. UE's Z is our Y.
+ * The directions are made as the LCG stream runs, ray after ray: a seed of 0 drives two
+ * 49-sample stratified uniform hemisphere sets on Shirley and Chiu's concentric map, and the second
+ * hemisphere's pole is negated (+Y and -Y hemispheres).
  *
  * ```wgsl
  * fn blas_query_band_sdf(point: vec3<f32>, geometry_index: u32, band: f32, two_sided: bool, contact, stack, stack_top: u32) -> f32
@@ -55,7 +54,7 @@ const BLAS_BAND_VOTE_STRATA = ${BLAS_BAND_VOTE_STRATA}u;
 const BLAS_BAND_VOTE_HEMISPHERE = ${BLAS_BAND_VOTE_STRATA * BLAS_BAND_VOTE_STRATA}u;
 const BLAS_BAND_VOTE_RAYS = ${BLAS_BAND_VOTE_RAYS}u;
 
-/** FRandomStream::GetFraction: the stream's next fraction in [0, 1) */
+/** Next LCG fraction in [0, 1) */
 fn blas_band_vote_fraction(seed: ptr<function, u32>) -> f32 {
     *seed = *seed * 196314165u + 907633515u;
 
@@ -145,7 +144,7 @@ fn blas_query_band_sdf(
         }
     }
 
-    // UE's Hit > 0 && HitBack > 0.25 · samples, of which the first follows from the second
+    // Inside when hits > 0 and back-face hits > 0.25 · samples (the first follows from the second)
     return select(distance, -distance, 4u * back > BLAS_BAND_VOTE_RAYS);
 }
 `, [

package/src/shade/renderer/geometry/virtual/proxy/vgeo_to_proxy_mesh.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Turn a virtual geometry into an ordinary meshlet geometry of at most `triangle_limit` triangles: a
+ * proxy, for whatever wants a plain mesh of an asset that is only clusters.
+ *
+ * **No simplification happens here.** The DAG already holds the asset at every level of detail; the
+ * proxy is a cut through it, and the cut's clusters are meshlets already (`VGEO_FORMAT.md` §8). The
+ * cut starts at the roots and refines, one group at a time, the group whose parents carry the largest
+ * `self_error`, and stops at the first refinement that would take it over the limit — so the error is
+ * as uniform as the DAG allows.
+ *
+ * A group is refined only once every one of its parents is in the cut (`group_parent_count`, §6), and
+ * then all of them are replaced together, so the cut is watertight at every step, as a view's cut is.
+ *
+ * Pages are installed as the descent reaches them, down to one band below the cut: a small proxy of a
+ * large asset reads the coarse prefix of the file and nothing else.
+ *
+ * The DAG's roots are as coarse as it goes: a limit below the roots' triangle count gets the roots.
+ *
+ * @param {VGeoContainerReader} reader an open container, which is one material's geometry; the pages the
+ *     descent reaches are installed into it and left there
+ * @param {number} triangle_limit
+ * @returns {Promise<MeshletGeometry>}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_to_proxy_mesh(reader: VGeoContainerReader, triangle_limit: number): Promise<MeshletGeometry>;
+export type VGeoContainerReader = import("../format/read/VGeoContainerReader.js").VGeoContainerReader;
+export type VGeoPage = import("../format/read/VGeoPage.js").VGeoPage;
+import { MeshletGeometry } from "../../MeshletGeometry.js";
+//# sourceMappingURL=vgeo_to_proxy_mesh.d.ts.map

package/src/shade/renderer/geometry/virtual/proxy/vgeo_to_proxy_mesh.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_to_proxy_mesh.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/proxy/vgeo_to_proxy_mesh.js"],"names":[],"mappings":"AAuBA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,2CARW,mBAAmB,kBAEnB,MAAM,GACJ,QAAQ,eAAe,CAAC,CAcpC;kCA7CY,OAAO,uCAAuC,EAAE,mBAAmB;uBACnE,OAAO,4BAA4B,EAAE,QAAQ;gCAP1B,0BAA0B"}

package/src/shade/renderer/geometry/virtual/proxy/vgeo_to_proxy_mesh.js

@@ -0,0 +1,343 @@
+import { assert } from "../../../../../core/assert.js";
+import { BinaryBuffer } from "../../../../../core/binary/BinaryBuffer.js";
+import { platform_compute_endianness } from "../../../../../core/binary/platform_compute_endianness.js";
+import { IndexedFloatMaxHeap } from "../../../../../core/collection/heap/IndexedFloatMaxHeap.js";
+import { aabb3_array_combine } from "../../../../../core/geom/3d/aabb/aabb3_array_combine.js";
+import { blas_from_meshlets } from "../../blas_from_meshlets.js";
+import { MESHLET_METADATA_STRUCT } from "../../meshlet/encoding/MESHLET_METADATA_STRUCT.js";
+import { MeshletGeometry } from "../../MeshletGeometry.js";
+import { VGEO_NO_CHILD } from "../format/cluster/VGEO_NO_CHILD.js";
+import { VGEO_SAME_PAGE } from "../format/cluster/VGEO_SAME_PAGE.js";
+import { vgeo_meshlet_metadata_write } from "../runtime/vgeo_meshlet_metadata_write.js";
+
+/**
+ * @typedef {import("../format/read/VGeoContainerReader.js").VGeoContainerReader} VGeoContainerReader
+ * @typedef {import("../format/read/VGeoPage.js").VGeoPage} VGeoPage
+ */
+
+/**
+ * A page not yet given its groups' ids.
+ * @type {number}
+ */
+const NO_BASE = -1;
+
+/**
+ * Turn a virtual geometry into an ordinary meshlet geometry of at most `triangle_limit` triangles: a
+ * proxy, for whatever wants a plain mesh of an asset that is only clusters.
+ *
+ * **No simplification happens here.** The DAG already holds the asset at every level of detail; the
+ * proxy is a cut through it, and the cut's clusters are meshlets already (`VGEO_FORMAT.md` §8). The
+ * cut starts at the roots and refines, one group at a time, the group whose parents carry the largest
+ * `self_error`, and stops at the first refinement that would take it over the limit — so the error is
+ * as uniform as the DAG allows.
+ *
+ * A group is refined only once every one of its parents is in the cut (`group_parent_count`, §6), and
+ * then all of them are replaced together, so the cut is watertight at every step, as a view's cut is.
+ *
+ * Pages are installed as the descent reaches them, down to one band below the cut: a small proxy of a
+ * large asset reads the coarse prefix of the file and nothing else.
+ *
+ * The DAG's roots are as coarse as it goes: a limit below the roots' triangle count gets the roots.
+ *
+ * @param {VGeoContainerReader} reader an open container, which is one material's geometry; the pages the
+ *     descent reaches are installed into it and left there
+ * @param {number} triangle_limit
+ * @returns {Promise<MeshletGeometry>}
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export async function vgeo_to_proxy_mesh(reader, triangle_limit) {
+    assert.defined(reader.root, 'reader.root — the container must be open');
+    assert.isNonNegativeInteger(triangle_limit, 'triangle_limit');
+
+    const cut = new ProxyCut(reader);
+
+    await cut.descend(triangle_limit);
+
+    return cut.build();
+}
+
+/**
+ * The cut, and the bookkeeping of its descent.
+ *
+ * Groups are given dense ids as their page is installed, so the per-group state is typed arrays sized
+ * once from the header's `total_groups`.
+ */
+class ProxyCut {
+    /**
+     * @param {VGeoContainerReader} reader
+     */
+    constructor(reader) {
+        this.reader = reader;
+
+        const capacity = reader.header.total_groups;
+
+        /**
+         * First group id of each page; {@link NO_BASE} until the page is installed.
+         */
+        this.page_base = new Int32Array(reader.header.total_pages).fill(NO_BASE);
+
+        this.next_base = 0;
+
+        this.group_page = new Uint32Array(capacity);
+        this.group_index = new Uint16Array(capacity);
+
+        /**
+         * Parents of the group in the cut so far.
+         */
+        this.arrived = new Uint16Array(capacity);
+
+        /**
+         * Their triangles: what refining the group takes out of the cut.
+         */
+        this.parent_triangles = new Uint32Array(capacity);
+
+        this.refined = new Uint8Array(capacity);
+
+        /**
+         * Groups whose every parent is in the cut, by the error those parents carry.
+         */
+        this.refinable = new IndexedFloatMaxHeap(capacity);
+
+        /**
+         * Every cluster that entered the cut, as the id of its group, its index in its page and the id
+         * of its child group (-1 for a leaf). One leaves the cut when its child group is refined.
+         * @type {number[]}
+         */
+        this.entered_group = [];
+        this.entered_cluster = [];
+        this.entered_child = [];
+
+        this.triangle_count = 0;
+    }
+
+    /**
+     * @param {number} limit
+     * @returns {Promise<void>}
+     */
+    async descend(limit) {
+        const root = this.reader.root;
+
+        this.#register(root);
+
+        for (let group = 0; group < root.group_parent_count.length; group++) {
+            // no cluster refines into it: the top of the DAG
+            if (root.group_parent_count[group] === 0) {
+                await this.#enter(this.page_base[root.index] + group);
+            }
+        }
+
+        const refinable = this.refinable;
+
+        while (refinable.size > 0) {
+            const id = refinable.pop_max();
+
+            if (this.triangle_count - this.parent_triangles[id] + this.#group_triangles(id) > limit) {
+                // the largest error left does not fit: refining anywhere finer would make it less uniform
+                break;
+            }
+
+            this.refined[id] = 1;
+            this.triangle_count -= this.parent_triangles[id];
+
+            await this.#enter(id);
+        }
+    }
+
+    /**
+     * The cut's clusters as a meshlet geometry: their payloads gathered as they are stored, a metadata
+     * row each, and the BVH the mesh path builds.
+     *
+     * @returns {MeshletGeometry}
+     */
+    build() {
+        /** @type {VGeoPage[]} */
+        const pages = [];
+        /** @type {number[]} */
+        const clusters = [];
+
+        let data_size = 0;
+
+        for (let i = 0; i < this.entered_group.length; i++) {
+            const child = this.entered_child[i];
+
+            if (child !== -1 && this.refined[child] === 1) {
+                continue;
+            }
+
+            const page = this.reader.page(this.group_page[this.entered_group[i]]);
+            const cluster = this.entered_cluster[i];
+
+            pages.push(page);
+            clusters.push(cluster);
+
+            data_size += page.cluster_payload_size[cluster];
+        }
+
+        const count = clusters.length;
+
+        const data = new Uint8Array(data_size);
+
+        const metadata = BinaryBuffer.fromEndianness(platform_compute_endianness());
+
+        metadata.setCapacity(count * MESHLET_METADATA_STRUCT.size);
+
+        const result = new MeshletGeometry();
+
+        const box = result.bounding_box;
+
+        box.set([Infinity, Infinity, Infinity, -Infinity, -Infinity, -Infinity]);
+
+        let address = 0;
+
+        for (let i = 0; i < count; i++) {
+            const page = pages[i];
+            const cluster = clusters[i];
+
+            const start = page.payload_offset + page.cluster_payload_offset[cluster];
+            const size = page.cluster_payload_size[cluster];
+
+            data.set(page.bytes.subarray(start, start + size), address);
+
+            // §11.8: every payload size is a multiple of four, so each cluster starts on a word
+            vgeo_meshlet_metadata_write(metadata, page, cluster, address >>> 2);
+
+            // `aabb` is the cluster's tight fit, so their union is the proxy's
+            aabb3_array_combine(box, 0, box, 0, page.aabb, cluster * 6);
+
+            address += size;
+        }
+
+        const batch = result.meshlets;
+
+        batch.count = count;
+        batch.data_buffer = data.buffer;
+        batch.metadata_buffer = metadata.data.slice(0, count * MESHLET_METADATA_STRUCT.size);
+
+        // the box-diagonal sphere `meshlet_geometry_build_from_geometry` gives a mesh
+        const sphere = result.bounding_sphere;
+
+        sphere[0] = (box[0] + box[3]) * 0.5;
+        sphere[1] = (box[1] + box[4]) * 0.5;
+        sphere[2] = (box[2] + box[5]) * 0.5;
+        sphere[3] = 0.5 * Math.hypot(box[3] - box[0], box[4] - box[1], box[5] - box[2]);
+
+        result.name = this.reader.source.name;
+        result.primitive_count = this.triangle_count;
+        result.bvh = blas_from_meshlets(batch, result.primitive_count, box);
+
+        return result;
+    }
+
+    /**
+     * @param {number} id
+     * @returns {number}
+     */
+    #group_triangles(id) {
+        const page = this.reader.page(this.group_page[id]);
+        const group = this.group_index[id];
+
+        const first = page.group_cluster_first[group];
+        const end = first + page.group_cluster_count[group];
+
+        let triangles = 0;
+
+        for (let cluster = first; cluster < end; cluster++) {
+            triangles += page.triangle_count[cluster];
+        }
+
+        return triangles;
+    }
+
+    /**
+     * Give an installed page's groups their ids.
+     *
+     * @param {VGeoPage} page
+     */
+    #register(page) {
+        if (this.page_base[page.index] !== NO_BASE) {
+            return;
+        }
+
+        const base = this.next_base;
+        const group_count = page.group_cluster_count.length;
+
+        this.page_base[page.index] = base;
+
+        for (let group = 0; group < group_count; group++) {
+            this.group_page[base + group] = page.index;
+            this.group_index[base + group] = group;
+        }
+
+        this.next_base = base + group_count;
+    }
+
+    /**
+     * Put a group's clusters in the cut, and count each in at its child group, which becomes
+     * refinable once its last parent arrives.
+     *
+     * @param {number} id
+     * @returns {Promise<void>}
+     */
+    async #enter(id) {
+        const reader = this.reader;
+        const page = reader.page(this.group_page[id]);
+        const group = this.group_index[id];
+
+        const first = page.group_cluster_first[group];
+        const end = first + page.group_cluster_count[group];
+
+        // the child pages first: a child group's parent count lives in its own page
+        const installs = [];
+
+        for (let cluster = first; cluster < end; cluster++) {
+            const child_ref = page.child_ref[cluster];
+
+            if (child_ref === VGEO_NO_CHILD || child_ref === VGEO_SAME_PAGE) {
+                continue;
+            }
+
+            const child_page = page.child_page_index[child_ref];
+
+            if (!reader.is_resident(child_page)) {
+                installs.push(reader.install(
+                    child_page, page.child_frame_offset[child_ref], page.child_fetch_size[child_ref]
+                ));
+            }
+        }
+
+        for (const child_page of await Promise.all(installs)) {
+            this.#register(child_page);
+        }
+
+        for (let cluster = first; cluster < end; cluster++) {
+            const triangles = page.triangle_count[cluster];
+
+            this.triangle_count += triangles;
+
+            this.entered_group.push(id);
+            this.entered_cluster.push(cluster);
+
+            const child_ref = page.child_ref[cluster];
+
+            if (child_ref === VGEO_NO_CHILD) {
+                this.entered_child.push(-1);
+                continue;
+            }
+
+            const child_page = reader.page(child_ref === VGEO_SAME_PAGE ? page.index : page.child_page_index[child_ref]);
+            const child_group = page.child_group[cluster];
+            const child = this.page_base[child_page.index] + child_group;
+
+            this.entered_child.push(child);
+
+            this.arrived[child]++;
+            this.parent_triangles[child] += triangles;
+
+            if (this.arrived[child] === child_page.group_parent_count[child_group]) {
+                this.refinable.insert(child, page.self_error[cluster]);
+            }
+        }
+    }
+}

package/src/shade/renderer/geometry/virtual/runtime/vgeo_meshlet_metadata_write.d.ts

@@ -0,0 +1,17 @@
+/**
+ * One cluster's meshlet metadata row, written at `buffer`'s position.
+ *
+ * `VGEO_FORMAT.md` §8: the 40-byte rows are synthesized from the cluster record — `aabb` becomes
+ * `bounds_box`, the u8 counts widen to u32, `encoding_flags` passes through. Only `address` depends
+ * on where the payload went, so the caller says.
+ *
+ * @param {BinaryBuffer} buffer
+ * @param {VGeoPage} page
+ * @param {number} cluster index within `page`
+ * @param {number} address where the cluster's payload starts in the data the row will be read against, in 4-byte words
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_meshlet_metadata_write(buffer: BinaryBuffer, page: VGeoPage, cluster: number, address: number): void;
+//# sourceMappingURL=vgeo_meshlet_metadata_write.d.ts.map

package/src/shade/renderer/geometry/virtual/runtime/vgeo_meshlet_metadata_write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vgeo_meshlet_metadata_write.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/vgeo_meshlet_metadata_write.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;GAcG;AACH,2FANW,MAAM,WACN,MAAM,QAahB"}

package/src/shade/renderer/geometry/virtual/runtime/vgeo_meshlet_metadata_write.js

@@ -0,0 +1,29 @@
+import { write_wgsl_type_value } from "../../../shader/type/serde/write_gpu_typed_buffer.js";
+import {
+    MESHLET_METADATA_STRUCT
+} from "../../meshlet/encoding/MESHLET_METADATA_STRUCT.js";
+
+/**
+ * One cluster's meshlet metadata row, written at `buffer`'s position.
+ *
+ * `VGEO_FORMAT.md` §8: the 40-byte rows are synthesized from the cluster record — `aabb` becomes
+ * `bounds_box`, the u8 counts widen to u32, `encoding_flags` passes through. Only `address` depends
+ * on where the payload went, so the caller says.
+ *
+ * @param {BinaryBuffer} buffer
+ * @param {VGeoPage} page
+ * @param {number} cluster index within `page`
+ * @param {number} address where the cluster's payload starts in the data the row will be read against, in 4-byte words
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function vgeo_meshlet_metadata_write(buffer, page, cluster, address) {
+    write_wgsl_type_value({
+        bounds_box: page.aabb.subarray(cluster * 6, cluster * 6 + 6),
+        address,
+        primitive_count: page.triangle_count[cluster],
+        vertex_count: page.vertex_count[cluster],
+        flags: page.encoding_flags[cluster],
+    }, buffer, MESHLET_METADATA_STRUCT);
+}

package/src/shade/renderer/geometry/virtual/runtime/vgeo_runtime_meshlet_batch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vgeo_runtime_meshlet_batch.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/vgeo_runtime_meshlet_batch.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,4DALa,YAAY,CA6CxB;6BA9D4B,+BAA+B"}
+{"version":3,"file":"vgeo_runtime_meshlet_batch.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/runtime/vgeo_runtime_meshlet_batch.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,4DALa,YAAY,CAuCxB;6BAzD4B,+BAA+B"}

package/src/shade/renderer/geometry/virtual/runtime/vgeo_runtime_meshlet_batch.js

@@ -1,11 +1,11 @@
 import { assert } from "../../../../../core/assert.js";
 import { BinaryBuffer } from "../../../../../core/binary/BinaryBuffer.js";
 import { platform_compute_endianness } from "../../../../../core/binary/platform_compute_endianness.js";
-import { write_wgsl_type_value } from "../../../shader/type/serde/write_gpu_typed_buffer.js";
 import {
     MESHLET_METADATA_STRUCT
 } from "../../meshlet/encoding/MESHLET_METADATA_STRUCT.js";
 import { MeshletBatch } from "../../meshlet/MeshletBatch.js";
+import { vgeo_meshlet_metadata_write } from "./vgeo_meshlet_metadata_write.js";
 
 /**
  * A decoded page, as the meshlet pool takes it.
@@ -46,18 +46,12 @@ export function vgeo_runtime_meshlet_batch(page) {
     metadata.setCapacity(count * MESHLET_METADATA_STRUCT.size);
 
     for (let cluster = 0; cluster < count; cluster++) {
-        write_wgsl_type_value({
-            bounds_box: page.aabb.subarray(cluster * 6, cluster * 6 + 6),
-            /*
-             Words, and relative to the page's payload section — `GPUMeshletManager` adds the
-             allocation's own offset when it uploads. Format §11.8 makes every payload offset a
-             multiple of four, so this division is exact rather than rounded.
-             */
-            address: page.cluster_payload_offset[cluster] >>> 2,
-            primitive_count: page.triangle_count[cluster],
-            vertex_count: page.vertex_count[cluster],
-            flags: page.encoding_flags[cluster],
-        }, metadata, MESHLET_METADATA_STRUCT);
+        /*
+         Words, and relative to the page's payload section — `GPUMeshletManager` adds the
+         allocation's own offset when it uploads. Format §11.8 makes every payload offset a
+         multiple of four, so this division is exact rather than rounded.
+         */
+        vgeo_meshlet_metadata_write(metadata, page, cluster, page.cluster_payload_offset[cluster] >>> 2);
     }
 
     // `BinaryBuffer.data` is the ArrayBuffer itself, and `setCapacity` may have rounded it up;

package/src/shade/renderer/global_illumination/probe_clipmap/GPUProbeClipmapGI.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUProbeClipmapGI.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/probe_clipmap/GPUProbeClipmapGI.js"],"names":[],"mappings":"AAeA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IA0DI;;OAEG;IACH,sBAFW,eAAe,EAMzB;IAED;;OAEG;IACH,qCAEC;IAED;;OAEG;IACH,qCAEC;IAED;;OAEG;IACH,oCAEC;IAED;;;;;;;;;;;;;;OAcG;IACH;QAT+B,KAAK,EAAzB,UAAU;QACc,IAAI,EAA5B,cAAc;QACgB,QAAQ,EAAtC,oBAAoB;QACJ,KAAK,EAArB,MAAM;QACU,MAAM,EAAtB,MAAM;QACK,IAAI;QACE,MAAM,GAAvB,MAAM;aAiGhB;IAED;;;OAGG;IACH,0BAEC;IAED;;;;;;;;;OASG;IACH,4CAUC;IAwDD;;;;;;;;;;OAUG;IACH;QAN+B,KAAK,EAAzB,UAAU;QACc,IAAI,EAA5B,cAAc;QACgB,QAAQ,EAAtC,oBAAoB;QACF,UAAU,EAA5B,MAAM,EAAE;QACN,MAAM,CAmBlB;IAED;;;;;OAKG;IACH,uBAFW,aAAa,QASvB;IAED;;;OAGG;IACH,0BAHW,aAAa,GACX,OAAO,CAanB;IAyCD;;;OAGG;IACH,gBAoBC;IAED,gBAcC;;CACJ;yBApcY,OAAO,8DAA8D,EAAE,UAAU;8BACjF,OAAO,0BAA0B,EAAE,eAAe;6BAClD,OAAO,8BAA8B,EAAE,cAAc;mCACrD,OAAO,2BAA2B,EAAE,oBAAoB;4BACxD,OAAO,4BAA4B,EAAE,aAAa;gCAjB/B,4BAA4B;gCAQ5B,4BAA4B;uCAErB,6BAA6B"}
+{"version":3,"file":"GPUProbeClipmapGI.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/probe_clipmap/GPUProbeClipmapGI.js"],"names":[],"mappings":"AAeA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IA0DI;;OAEG;IACH,sBAFW,eAAe,EAMzB;IAED;;OAEG;IACH,qCAEC;IAED;;OAEG;IACH,qCAEC;IAED;;OAEG;IACH,oCAEC;IAED;;;;;;;;;;;;;;OAcG;IACH;QAT+B,KAAK,EAAzB,UAAU;QACc,IAAI,EAA5B,cAAc;QACgB,QAAQ,EAAtC,oBAAoB;QACJ,KAAK,EAArB,MAAM;QACU,MAAM,EAAtB,MAAM;QACK,IAAI;QACE,MAAM,GAAvB,MAAM;aA2FhB;IAED;;;OAGG;IACH,0BAEC;IAED;;;;;;;;;OASG;IACH,4CAUC;IAwDD;;;;;;;;;;OAUG;IACH;QAN+B,KAAK,EAAzB,UAAU;QACc,IAAI,EAA5B,cAAc;QACgB,QAAQ,EAAtC,oBAAoB;QACF,UAAU,EAA5B,MAAM,EAAE;QACN,MAAM,CAmBlB;IAED;;;;;OAKG;IACH,uBAFW,aAAa,QASvB;IAED;;;OAGG;IACH,0BAHW,aAAa,GACX,OAAO,CAanB;IAyCD;;;OAGG;IACH,gBAoBC;IAED,gBAcC;;CACJ;yBA9bY,OAAO,8DAA8D,EAAE,UAAU;8BACjF,OAAO,0BAA0B,EAAE,eAAe;6BAClD,OAAO,8BAA8B,EAAE,cAAc;mCACrD,OAAO,2BAA2B,EAAE,oBAAoB;4BACxD,OAAO,4BAA4B,EAAE,aAAa;gCAjB/B,4BAA4B;gCAQ5B,4BAA4B;uCAErB,6BAA6B"}

package/src/shade/renderer/global_illumination/probe_clipmap/GPUProbeClipmapGI.js

@@ -180,12 +180,6 @@ export class GPUProbeClipmapGI {
 
         const scene = view.scene;
         const sdf = scene.geometries.sdf;
-        const materials = this.#graphics.materials_resident;
-
-        // the scene's materials as they are this frame: a repack recaptures its pairs
-        materials.ensure_scene_materials(scene);
-        materials.update();
-
         sdf.configure(settings.mesh_sdf_voxel_size, settings.mesh_sdf_max_bricks);
         sdf.trim();
         sdf.cards.capture_mode = settings.card_capture_mode;
@@ -193,7 +187,7 @@ export class GPUProbeClipmapGI {
             graph,
             budget: settings.mesh_sdf_bake_budget,
             capture_budget: settings.card_capture_budget,
-            materials,
+            materials: this.#graphics.materials_resident,
             material_contexts: this.#graphics.materials,
         });
 
@@ -235,8 +229,8 @@ export class GPUProbeClipmapGI {
             brick_clipmap: this.#brick_clipmap,
             bricks,
             scene,
-            materials,
             card_rows: this.#holds.rows_buffer,
+            resampling: settings.resampling,
         });
     }
 

package/src/shade/renderer/global_illumination/probe_clipmap/ProbeClipmapSceneHolds.d.ts

@@ -15,8 +15,8 @@
  * its hold and its pair, the new ones taken before the old ones go, so a cache or card set a row keeps
  * drawing is never let go in between.
  *
- * When the resident material context repacks a material whose version moved, each of that
- * material's pairs is recaptured (§6.5), and the holds of its rows move to the side it draws now.
+ * When the material manager restages a material whose version moved, each of that material's pairs
+ * is recaptured (§6.5), and the holds of its rows move to the side it draws now.
  *
  * {@link attach} subscribes and walks the rows already there; {@link detach} gives every hold and card
  * set back. Neither trims: a cache with no holder stays until its user trims, so leaving the mode keeps
@@ -25,7 +25,7 @@
 export class ProbeClipmapSceneHolds {
     /**
      * @param {GPUSceneContext} scene
-     * @param {GraphicsContext} graphics whose resident materials' repacks recapture the pairs of the material
+     * @param {GraphicsContext} graphics whose material manager's restages recapture the pairs of the material
      */
     constructor(scene: GPUSceneContext, graphics: GraphicsContext);
     /**
@@ -43,7 +43,7 @@ export class ProbeClipmapSceneHolds {
      */
     get pair_count(): number;
     /**
-     * Recaptures asked for, a pair each time its material was repacked.
+     * Recaptures asked for, a pair each time its material was restaged.
      * @returns {number}
      */
     get recaptures_requested(): number;
@@ -79,6 +79,6 @@ export type GPUSceneContext = import("../../scene/GPUSceneContext.js").GPUSceneC
 export type MeshletGeometry = import("../../geometry/MeshletGeometry.js").MeshletGeometry;
 export type GPUGeometryMetadata = import("../../geometry/GPUGeometryMetadata.js").GPUGeometryMetadata;
 export type ShadeMaterial = import("../../material/ShadeMaterial.js").ShadeMaterial;
-export type GPUResidentMaterialContext = import("../../material/resident/GPUResidentMaterialContext.js").GPUResidentMaterialContext;
+export type GPUMaterialManager = import("../../material/GPUMaterialManager.js").GPUMaterialManager;
 export type GraphicsContext = import("../../GraphicsContext.js").GraphicsContext;
 //# sourceMappingURL=ProbeClipmapSceneHolds.d.ts.map