@woosh/meep-engine 3.58.0 → 3.60.0

package/src/shade/renderer/geometry/virtual/sdf/VGeoSDFProxies.js

@@ -0,0 +1,902 @@
+import { assert } from "../../../../../core/assert.js";
+import { BufferDescriptor } from "../../../../descriptor/buffer/BufferDescriptor.js";
+import { BufferResourceDescriptor } from "../../../../device/graph/BufferResourceDescriptor.js";
+import { graph_read_buffer } from "../../../buffer/graph_read_buffer.js";
+import { graph_build_indirect_dispatch_command } from "../../../gpu_primitive/indirect/IndirectComputeCommandBuildPass.js";
+import {
+    graph_prefix_scan_csdldf,
+    prefix_scan_csdldf_output_descriptor
+} from "../../../gpu_primitive/prefix_sum/v1/graph_prefix_scan_csdldf.js";
+import { graph_create_buffer } from "../../../shader/graph/graph_create_buffer.js";
+import { Attribute } from "../../Attribute.js";
+import { Geometry } from "../../Geometry.js";
+import { MeshoptClusterizer } from "../../meshlet/build/meshoptimizer/meshopt_clusterizer.js";
+import { meshlet_geometry_build_from_geometry } from "../../meshlet_geometry_build_from_geometry.js";
+import { MeshSDFState } from "../../sdf/MESH_SDF.js";
+import { MeshSDFLayout } from "../../sdf/MeshSDFLayout.js";
+import { StandardAttributes } from "../../StandardAttributes.js";
+import { vgeo_feedback_slot_stats } from "../runtime/cut/vgeo_cut_feedback_layout.js";
+import { graph_vgeo_cut_descent } from "../runtime/graph_vgeo_cut_descent.js";
+import { VGEO_CUT_STAT } from "../runtime/layout/VGEO_CUT_STAT.js";
+import { VGEO_CUT_STAT_COUNT } from "../runtime/layout/VGEO_CUT_STAT_COUNT.js";
+import { VGEO_GEOMETRY_ROW_NONE } from "../runtime/layout/VGEO_GEOMETRY_ROW_NONE.js";
+import { VGEO_INSTANCE_WORDS } from "../runtime/layout/VGEO_INSTANCE_WORDS.js";
+import { VGeoViewCut } from "../runtime/VGeoViewCut.js";
+import { shader_vgeo_sdf_collect, VGEO_SDF_COLLECT_WORKGROUP_SIZE } from "./shader_vgeo_sdf_collect.js";
+import { shader_vgeo_sdf_decode } from "./shader_vgeo_sdf_decode.js";
+import { shader_vgeo_sdf_traverse } from "./shader_vgeo_sdf_traverse.js";
+import {
+    VGEO_SDF_CLUSTER_WORDS,
+    VGEO_SDF_COUNTER,
+    VGEO_SDF_COUNTER_WORDS,
+    VGEO_SDF_JOB_STRUCT,
+    vgeo_sdf_header_words
+} from "./VGEO_SDF.js";
+
+/**
+ * @typedef {import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
+ * @typedef {import("../../GPUGeometryManager.js").GPUGeometryManager} GPUGeometryManager
+ * @typedef {import("../../GPUGeometryMetadata.js").GPUGeometryMetadata} GPUGeometryMetadata
+ * @typedef {import("../../MeshletGeometry.js").MeshletGeometry} MeshletGeometry
+ * @typedef {import("../runtime/GPUVirtualGeometryRuntime.js").GPUVirtualGeometryRuntime} GPUVirtualGeometryRuntime
+ */
+
+/** The slot holds no geometry. */
+const JOB_FREE = 0;
+/** Cut each frame, its counters read back. */
+const JOB_CUT = 1;
+/** Its last cut read back stood nothing in: the next frame it is cut, its mesh is written out too. */
+const JOB_READY = 2;
+/** Written out in a frame whose readback has not landed. */
+const JOB_DECODING = 3;
+/** Its mesh is read back: its proxy is built on the host. */
+const JOB_BUILD = 4;
+/** Its proxy is baked by the mesh path. */
+const JOB_BAKING = 5;
+/** Its proxy's cache is resident: given to the geometry at the next update. */
+const JOB_BAKED = 6;
+
+/**
+ * Frames whose readback may be in flight before a frame's cut is skipped, as the bake's log: a mapping lands a frame or
+ * two after its copy, and past this the device is behind.
+ * @type {number}
+ */
+const MAX_FRAMES_IN_FLIGHT = 3;
+
+/**
+ * Geometries extracted at once: the jobs cut each frame until their cut stands nothing in. One whose proxy is built,
+ * baking or waiting to be given its cache keeps its slot until then.
+ * @type {number}
+ */
+const DEFAULT_JOB_CAPACITY = 32;
+
+/**
+ * Entries the cluster list starts with: a cut of a typical geometry at half its cache's voxel is under 128 clusters
+ * (S8, step 0), for each of {@link DEFAULT_JOB_CAPACITY} jobs. It doubles past what a frame's cut took.
+ * @type {number}
+ */
+const INITIAL_CLUSTER_CAPACITY = DEFAULT_JOB_CAPACITY * 128;
+
+/**
+ * One geometry being extracted.
+ */
+class VGeoSDFJob {
+    /**
+     * Bumped each time the slot takes a geometry: a readback of a frame cut for an earlier one is not this one's.
+     * @type {number}
+     */
+    generation = 0;
+
+    phase = JOB_FREE;
+
+    /**
+     * The geometry, whose cache is asked for.
+     * @type {GPUGeometryMetadata|null}
+     */
+    record = null;
+
+    /**
+     * What puts its error against a τ of 1: one over half its cache's level-0 voxel, in its own units.
+     * @type {number}
+     */
+    projection_k = 0;
+
+    /** What its last complete cut held. */
+    vertex_count = 0;
+    triangle_count = 0;
+
+    /** @type {Float32Array|null} */
+    positions = null;
+
+    /** @type {Uint32Array|null} */
+    indices = null;
+
+    /** @type {MeshletGeometry|null} */
+    proxy = null;
+
+    /** @type {GPUGeometryMetadata|null} */
+    proxy_record = null;
+}
+
+/**
+ * The jobs one recorded frame cut, for its readback.
+ */
+class VGeoSDFFrame {
+    busy = false;
+
+    count = 0;
+
+    /** @type {VGeoSDFJob[]} */
+    jobs = [];
+
+    /**
+     * @param {number} capacity
+     */
+    constructor(capacity) {
+        this.generations = new Uint32Array(capacity);
+        this.decoding = new Uint8Array(capacity);
+        this.vertex_bases = new Uint32Array(capacity);
+        this.triangle_bases = new Uint32Array(capacity);
+    }
+
+    vertex_offset = 0;
+    index_offset = 0;
+}
+
+/**
+ * The geometry caches of virtual geometry (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §7.8, as S8 built it): a
+ * {@link MeshSDFSource} of {@link GPUGeometrySDFManager}, which bakes a geometry's field from its tree, and a virtual
+ * geometry has none. Each virtual geometry whose cache is asked for gets a proxy, the triangles of a cut of it, baked by
+ * the mesh path as any geometry is, and its resident cache adopted into the geometry. Its instances are then composed
+ * from it as a mesh's are.
+ *
+ * **The cut.** A geometry is cut whole by the camera cut's own descent (`shader_vgeo_sdf_traverse`), at an error under
+ * half its cache's level-0 voxel, in its own space, under a feedback slot of the extraction's own: a cluster's page not
+ * resident is wanted there, as a view's are, and since a want lasts one reading the job is cut again each frame until
+ * its cut stands nothing in. Its counters are read back each frame.
+ *
+ * **The mesh.** The frame after a cut that stood nothing in, the job's clusters are written out too, its vertices as
+ * stored and its triangles as indices into them (`shader_vgeo_sdf_decode`), in room the last cut's counts made, and
+ * read back with that frame's counters. A frame that cut it otherwise (a page evicted since, the cut grown) is not
+ * taken, and the job is cut again.
+ *
+ * **The proxy.** One a frame, on the host: an ordinary geometry built from the mesh
+ * (`meshlet_geometry_build_from_geometry`, which costs 2.2 to 4.1 µs a triangle, measured), added to the geometry
+ * manager, its cache held with the side the geometry's holders draw. When its bake turns resident the next update gives
+ * it to the geometry ({@link GPUGeometrySDFManager#adopt}) and removes the proxy.
+ *
+ * A geometry no longer asked for when its turn comes is let go, and one whose holders ask again is extracted again.
+ * Settings that change the caches' voxel restart every job.
+ */
+export class VGeoSDFProxies {
+
+    /** @type {GPUDevice} */
+    #device;
+
+    /** @type {GPUVirtualGeometryRuntime} */
+    #runtime;
+
+    /** @type {GPUGeometryManager} */
+    #geometries;
+
+    /** @type {import("../../sdf/GPUGeometrySDFManager.js").GPUGeometrySDFManager} */
+    #sdf;
+
+    /**
+     * The extraction's cut: its slot, its params and its wavefront bound.
+     * @type {VGeoViewCut}
+     */
+    #cut;
+
+    /** @type {VGeoSDFJob[]} */
+    #jobs = [];
+
+    /**
+     * Geometries asked for and not yet a job's, in the order asked; a geometry asked for again or let go since may be
+     * here, and is passed over.
+     * @type {GPUGeometryMetadata[]}
+     */
+    #requested = [];
+
+    /** @type {VGeoSDFFrame[]} */
+    #frames = [];
+
+    #cluster_capacity = INITIAL_CLUSTER_CAPACITY;
+
+    /**
+     * The frame's jobs as the passes read them, `VGEO_SDF_JOB_STRUCT` each.
+     * @type {GPUBuffer}
+     */
+    #jobs_buffer;
+
+    #jobs_scratch;
+
+    #settings = { job_count: 0, cluster_capacity: 0, vertex_offset: 0, index_offset: 0 };
+
+    #collect_data = { instances: -1, claim_widths: -1 };
+    #collect_bindings = {};
+    #decode_data = { command: -1, clusters: -1, counters: -1, payload: -1 };
+    #decode_bindings = {};
+    #header_data = { counters: -1, feedback: -1, payload: -1 };
+
+    /** Where the extraction's slot keeps its counters in the frame's feedback, for the frame being recorded. */
+    #stats_base = 0;
+
+    #voxel_size;
+    #max_bricks;
+
+    #layout = new MeshSDFLayout();
+
+    #clusterizer_ready = false;
+
+    #extracted_count = 0;
+    #adopted_count = 0;
+    #triangles_extracted = 0;
+
+    #destroyed = false;
+
+    /**
+     * @param {Object} options
+     * @param {GPUDevice} options.device
+     * @param {GPUVirtualGeometryRuntime} options.runtime whose geometries' caches this makes
+     * @param {GPUGeometryManager} options.geometries the scene's, whose caches the virtual geometries' are
+     * @param {number} [options.job_capacity] geometries extracted at once
+     */
+    constructor({ device, runtime, geometries, job_capacity = DEFAULT_JOB_CAPACITY }) {
+        assert.defined(device, 'device');
+        assert.defined(runtime, 'runtime');
+        assert.defined(geometries, 'geometries');
+        assert.isPositiveInteger(job_capacity, 'job_capacity');
+
+        this.#device = device;
+        this.#runtime = runtime;
+        this.#geometries = geometries;
+        this.#sdf = geometries.sdf;
+        this.#cut = new VGeoViewCut({ device, label: 'vgeo sdf proxies' });
+
+        this.#voxel_size = this.#sdf.voxel_size;
+        this.#max_bricks = this.#sdf.max_bricks;
+
+        for (let i = 0; i < job_capacity; i++) {
+            this.#jobs.push(new VGeoSDFJob());
+        }
+
+        for (let i = 0; i < MAX_FRAMES_IN_FLIGHT; i++) {
+            this.#frames.push(new VGeoSDFFrame(job_capacity));
+        }
+
+        this.#jobs_buffer = device.createBuffer(BufferDescriptor.fromJSON({
+            label: 'VGeoSDFProxies/jobs',
+            size: job_capacity * VGEO_SDF_JOB_STRUCT.size,
+            usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST,
+        }));
+
+        this.#jobs_scratch = new DataView(new ArrayBuffer(job_capacity * VGEO_SDF_JOB_STRUCT.size));
+
+        const ready = MeshoptClusterizer.ready;
+
+        if (ready === undefined) {
+            this.#clusterizer_ready = true;
+        } else {
+            ready.then(() => {
+                this.#clusterizer_ready = true;
+            });
+        }
+
+        this.#sdf.onRequested.add(this.#requested_one, this);
+        this.#sdf.onBaked.add(this.#baked, this);
+        this.#sdf.add_source(this);
+    }
+
+    /**
+     * The extraction's cut, whose `stats` say what the last reading of its slot counted.
+     * @returns {VGeoViewCut}
+     */
+    get cut() {
+        return this.#cut;
+    }
+
+    /**
+     * Geometries being extracted.
+     * @returns {number}
+     */
+    get job_count() {
+        let count = 0;
+
+        for (const job of this.#jobs) {
+            if (job.phase !== JOB_FREE) {
+                count++;
+            }
+        }
+
+        return count;
+    }
+
+    /**
+     * Geometries asked for that wait for a job, those let go since included.
+     * @returns {number}
+     */
+    get requested_count() {
+        return this.#requested.length;
+    }
+
+    /**
+     * Proxies built so far.
+     * @returns {number}
+     */
+    get extracted_count() {
+        return this.#extracted_count;
+    }
+
+    /**
+     * Caches given to their geometries so far.
+     * @returns {number}
+     */
+    get adopted_count() {
+        return this.#adopted_count;
+    }
+
+    /**
+     * Triangles of the proxies built so far.
+     * @returns {number}
+     */
+    get triangles_extracted() {
+        return this.#triangles_extracted;
+    }
+
+    /**
+     * Entries the cluster list holds.
+     * @returns {number}
+     */
+    get cluster_capacity() {
+        return this.#cluster_capacity;
+    }
+
+    /**
+     * @param {GPUGeometryMetadata} record
+     */
+    #requested_one(record) {
+        if (record.vg_row !== VGEO_GEOMETRY_ROW_NONE) {
+            this.#requested.push(record);
+        }
+    }
+
+    /**
+     * @param {number} id
+     */
+    #baked(id) {
+        for (const job of this.#jobs) {
+            if (job.phase === JOB_BAKING && job.proxy_record.index === id) {
+                job.phase = JOB_BAKED;
+            }
+        }
+    }
+
+    /**
+     * The frame's work, ahead of the caches' bake: the caches baked given to their geometries, a proxy built, jobs
+     * started, and the jobs' cut recorded into `graph` while the runtime's frame is open.
+     *
+     * @param {FrameGraph} graph
+     */
+    graph_update(graph) {
+        assert.notOk(this.#destroyed, 'destroyed');
+
+        const sdf = this.#sdf;
+
+        if (sdf.voxel_size !== this.#voxel_size || sdf.max_bricks !== this.#max_bricks) {
+            // a cut for the old voxel bakes a proxy finer or coarser than the cache it is for
+            this.#restart();
+
+            this.#voxel_size = sdf.voxel_size;
+            this.#max_bricks = sdf.max_bricks;
+        }
+
+        this.#adopt();
+        this.#build();
+        this.#start();
+
+        if (this.#runtime.frame_open) {
+            this.#record(graph);
+        }
+    }
+
+    /**
+     * Give each geometry whose proxy is baked its cache, and remove the proxy.
+     */
+    #adopt() {
+        const sdf = this.#sdf;
+
+        for (const job of this.#jobs) {
+            if (job.phase !== JOB_BAKED) {
+                continue;
+            }
+
+            if (sdf.adopt(job.record, job.proxy_record)) {
+                this.#adopted_count++;
+            } else if (sdf.is_requested(job.record)) {
+                // the proxy's cache is not the one it was baked to: a proxy equal to another's is that one's record
+                this.#requested.push(job.record);
+            }
+
+            this.#free(job);
+        }
+    }
+
+    /**
+     * Build the proxy of the first job whose mesh is read back, and hold its cache.
+     */
+    #build() {
+        if (!this.#clusterizer_ready) {
+            return;
+        }
+
+        const sdf = this.#sdf;
+
+        for (const job of this.#jobs) {
+            if (job.phase !== JOB_BUILD) {
+                continue;
+            }
+
+            if (!sdf.is_requested(job.record)) {
+                // let go since its cut was taken
+                this.#free(job);
+                continue;
+            }
+
+            const mesh = new Geometry();
+
+            mesh.name = 'vgeo sdf proxy';
+            mesh.index = Attribute.from(job.indices, 1, StandardAttributes.Index);
+            mesh.addAttribute(Attribute.from(job.positions, 3, StandardAttributes.Position));
+
+            const proxy = meshlet_geometry_build_from_geometry(mesh);
+
+            this.#geometries.add(proxy);
+
+            job.proxy = proxy;
+            job.proxy_record = this.#geometries.get_metadata(proxy);
+            job.positions = null;
+            job.indices = null;
+            job.phase = JOB_BAKING;
+
+            this.#extracted_count++;
+            this.#triangles_extracted += job.triangle_count;
+
+            sdf.acquire(job.proxy_record, sdf.holds_two_sided(job.record));
+
+            if (sdf.state_of(job.proxy_record) === MeshSDFState.Resident) {
+                // a record a resident proxy of the same mesh already had
+                job.phase = JOB_BAKED;
+            }
+
+            return;
+        }
+    }
+
+    /**
+     * Give the free slots the geometries asked for, in the order asked.
+     */
+    #start() {
+        const sdf = this.#sdf;
+        const requested = this.#requested;
+        const layout = this.#layout;
+
+        let taken = 0;
+
+        for (const job of this.#jobs) {
+            if (job.phase !== JOB_FREE) {
+                continue;
+            }
+
+            while (taken < requested.length) {
+                const record = requested[taken++];
+
+                if (!sdf.is_requested(record) || this.#extracting(record)) {
+                    continue;
+                }
+
+                layout.compute(record.geometry.bounding_box, sdf.voxel_size, sdf.max_bricks);
+
+                job.generation++;
+                job.record = record;
+                job.projection_k = 1 / (0.5 * layout.voxel);
+                job.phase = JOB_CUT;
+
+                break;
+            }
+        }
+
+        requested.copyWithin(0, taken);
+        requested.length -= taken;
+    }
+
+    /**
+     * @param {GPUGeometryMetadata} record
+     * @returns {boolean} whether a job holds it
+     */
+    #extracting(record) {
+        for (const job of this.#jobs) {
+            if (job.phase !== JOB_FREE && job.record === record) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /**
+     * Let every job go, and ask again for the geometries still asked for.
+     */
+    #restart() {
+        for (const job of this.#jobs) {
+            if (job.phase === JOB_FREE) {
+                continue;
+            }
+
+            if (this.#sdf.is_requested(job.record)) {
+                this.#requested.push(job.record);
+            }
+
+            this.#free(job);
+        }
+    }
+
+    /**
+     * @param {VGeoSDFJob} job
+     */
+    #free(job) {
+        if (job.proxy !== null) {
+            this.#geometries.remove(job.proxy);
+        }
+
+        job.phase = JOB_FREE;
+        job.record = null;
+        job.positions = null;
+        job.indices = null;
+        job.proxy = null;
+        job.proxy_record = null;
+    }
+
+    /**
+     * @returns {VGeoSDFFrame|null}
+     */
+    #take_frame() {
+        for (const frame of this.#frames) {
+            if (!frame.busy) {
+                return frame;
+            }
+        }
+
+        return null;
+    }
+
+    /**
+     * Record the cut of the jobs that cut, and the write-out of those whose last cut stood nothing in.
+     *
+     * @param {FrameGraph} graph
+     */
+    #record(graph) {
+        const frame = this.#take_frame();
+
+        if (frame === null) {
+            return;
+        }
+
+        const runtime = this.#runtime;
+        const view = this.#jobs_scratch;
+        const stride = VGEO_SDF_JOB_STRUCT.size;
+
+        let count = 0;
+        let vertices = 0;
+        let triangles = 0;
+
+        for (const job of this.#jobs) {
+            if (job.phase !== JOB_CUT && job.phase !== JOB_READY) {
+                continue;
+            }
+
+            if (!this.#sdf.is_requested(job.record)) {
+                // let go since it was asked for: dropped, or forgotten
+                this.#free(job);
+                continue;
+            }
+
+            const decode = job.phase === JOB_READY;
+            const at = count * stride;
+
+            frame.jobs[count] = job;
+            frame.generations[count] = job.generation;
+            frame.decoding[count] = decode ? 1 : 0;
+            frame.vertex_bases[count] = vertices;
+            frame.triangle_bases[count] = triangles;
+
+            view.setUint32(at + VGEO_SDF_JOB_STRUCT.get("vg_row").offset, job.record.vg_row, true);
+            view.setFloat32(at + VGEO_SDF_JOB_STRUCT.get("projection_k").offset, job.projection_k, true);
+            view.setUint32(at + VGEO_SDF_JOB_STRUCT.get("decode").offset, decode ? 1 : 0, true);
+            view.setUint32(at + VGEO_SDF_JOB_STRUCT.get("vertex_base").offset, vertices, true);
+            view.setUint32(at + VGEO_SDF_JOB_STRUCT.get("triangle_base").offset, triangles, true);
+            view.setUint32(at + VGEO_SDF_JOB_STRUCT.get("vertex_count").offset, decode ? job.vertex_count : 0, true);
+            view.setUint32(at + VGEO_SDF_JOB_STRUCT.get("triangle_count").offset, decode ? job.triangle_count : 0, true);
+
+            if (decode) {
+                vertices += job.vertex_count;
+                triangles += job.triangle_count;
+                job.phase = JOB_DECODING;
+            }
+
+            count++;
+        }
+
+        if (count === 0) {
+            return;
+        }
+
+        frame.busy = true;
+        frame.count = count;
+
+        const header_words = vgeo_sdf_header_words(count);
+
+        frame.vertex_offset = header_words;
+        frame.index_offset = header_words + 3 * vertices;
+
+        const payload_bytes = 4 * (frame.index_offset + 3 * triangles);
+
+        this.#device.queue.writeBuffer(this.#jobs_buffer, 0, view.buffer, 0, count * stride);
+
+        const settings = this.#settings;
+
+        settings.job_count = count;
+        settings.cluster_capacity = this.#cluster_capacity;
+        settings.vertex_offset = frame.vertex_offset;
+        settings.index_offset = frame.index_offset;
+
+        // this frame's slot for the cut, and its params: a τ of 1, since its records carry the error's own scale
+        const slot = runtime.slot_of(this.#cut);
+
+        this.#cut.write_params({ runtime, slot, tau: 1 });
+        this.#stats_base = vgeo_feedback_slot_stats(slot);
+
+        // ----- the records: a job's geometry whole, then their claim widths scanned -----
+
+        const collect_data = this.#collect_data;
+        const collect = graph.add("VGeo SDF Collect", collect_data, this.#execute_collect);
+
+        collect_data.instances = collect.create("vgeo sdf instances", BufferResourceDescriptor.from(
+            count * VGEO_INSTANCE_WORDS * 4, GPUBufferUsage.STORAGE
+        ));
+        collect_data.claim_widths = collect.create("vgeo sdf claim widths", BufferResourceDescriptor.from(
+            16 + count * 4, GPUBufferUsage.STORAGE, 0, 16
+        ));
+
+        const prefix_sums = graph_prefix_scan_csdldf({
+            graph,
+            input: collect_data.claim_widths,
+            output: graph_create_buffer(graph, "vgeo sdf claim offsets", prefix_scan_csdldf_output_descriptor(count)),
+            element_max_count: count,
+        });
+
+        // ----- the cut: the camera cut's own descent, its clusters onto the list -----
+
+        const counters = graph_create_buffer(graph, "vgeo sdf counters", BufferResourceDescriptor.empty(
+            count * VGEO_SDF_COUNTER_WORDS * 4, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC
+        ));
+        const clusters = graph_create_buffer(graph, "vgeo sdf clusters", BufferResourceDescriptor.from(
+            16 + this.#cluster_capacity * VGEO_SDF_CLUSTER_WORDS * 4, GPUBufferUsage.STORAGE, 0, 16
+        ));
+
+        const descent = graph_vgeo_cut_descent({
+            graph,
+            runtime,
+            cut: this.#cut,
+            instances: collect_data.instances,
+            prefix_sums,
+            feedback: runtime.feedback_in(graph),
+            traverse: shader_vgeo_sdf_traverse,
+            bindings: { settings },
+            outputs: { vgeo_sdf_counters: counters, vgeo_sdf_clusters: clusters },
+        });
+
+        runtime.publish_feedback(graph, descent.feedback);
+
+        // ----- the write-out: a workgroup a listed cluster, every job's sizes and the ready jobs' meshes -----
+
+        const command = graph_build_indirect_dispatch_command(graph, descent.outputs.vgeo_sdf_clusters, 1, true);
+
+        const decode_data = this.#decode_data;
+        const decode = graph.add("VGeo SDF Decode", decode_data, this.#execute_decode);
+
+        decode_data.command = decode.read(command);
+        decode_data.clusters = decode.read(descent.outputs.vgeo_sdf_clusters);
+        decode_data.counters = decode.write(descent.outputs.vgeo_sdf_counters);
+        decode_data.payload = decode.create("vgeo sdf payload", BufferResourceDescriptor.from(
+            payload_bytes, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST
+        ));
+
+        // ----- the header: the jobs' counters and the cut's own, ahead of the meshes, then read back -----
+
+        const header_data = this.#header_data;
+        const header = graph.add("VGeo SDF Header", header_data, this.#execute_header);
+
+        header_data.counters = header.read(decode_data.counters);
+        header_data.feedback = header.read(descent.feedback);
+        header_data.payload = header.write(decode_data.payload);
+
+        graph_read_buffer({ graph, buffer: header_data.payload, offset: 0, size: payload_bytes })
+            .then(reference => {
+                try {
+                    if (!this.#destroyed) {
+                        this.#apply(new Uint32Array(reference.getValue()), frame);
+                    }
+                } finally {
+                    reference.release();
+                }
+            })
+            .catch(error => {
+                if (!this.#destroyed) {
+                    console.warn('VGeoSDFProxies: readback failed', error);
+                    this.#lose(frame);
+                }
+            })
+            .finally(() => {
+                frame.busy = false;
+            });
+    }
+
+    #execute_collect = (data, resources, execution) => {
+        const b = this.#collect_bindings;
+
+        b.settings = this.#settings;
+        b.vgeo_sdf_jobs = this.#jobs_buffer;
+        b.vg_geometries = this.#runtime.pool.buffer_geometries;
+        b.instances = resources.get(data.instances);
+        b.claim_widths = resources.get(data.claim_widths);
+
+        shader_vgeo_sdf_collect.dispatch({
+            encoder: execution.encoder,
+            group_count_x: Math.ceil(this.#settings.job_count / VGEO_SDF_COLLECT_WORKGROUP_SIZE),
+            bindings: b,
+        });
+    };
+
+    #execute_decode = (data, resources, execution) => {
+        const meshlets = this.#geometries.meshlets;
+        const b = this.#decode_bindings;
+
+        b.settings = this.#settings;
+        b.vgeo_sdf_jobs = this.#jobs_buffer;
+        b.vgeo_sdf_counters = resources.get(data.counters);
+        b.vgeo_sdf_clusters = resources.get(data.clusters);
+        b.meshlet_metadata = meshlets.buffer_metadata;
+        b.meshlet_data = meshlets.buffer_data;
+        b.vgeo_sdf_payload = resources.get(data.payload);
+
+        shader_vgeo_sdf_decode.dispatchIndirect({
+            encoder: execution.encoder,
+            command: resources.get(data.command),
+            command_offset: 0,
+            bindings: b,
+        });
+    };
+
+    #execute_header = (data, resources, execution) => {
+        const encoder = execution.encoder;
+        const payload = resources.get(data.payload);
+        const counter_bytes = 4 * this.#settings.job_count * VGEO_SDF_COUNTER_WORDS;
+
+        encoder.copyBufferToBuffer(resources.get(data.counters), 0, payload, 0, counter_bytes);
+        encoder.copyBufferToBuffer(resources.get(data.feedback), 4 * this.#stats_base, payload, counter_bytes, 4 * VGEO_CUT_STAT_COUNT);
+    };
+
+    /**
+     * A recorded frame's readback: each job's cut taken, its mesh too where the frame wrote it out.
+     *
+     * @param {Uint32Array} words
+     * @param {VGeoSDFFrame} frame
+     */
+    #apply(words, frame) {
+        const stats = frame.count * VGEO_SDF_COUNTER_WORDS;
+
+        // a subtree the cut left undescended is missing from every job's list, and no counter of a job says which
+        const holes = words[stats + VGEO_CUT_STAT.QUEUE_DROPPED] > 0
+            || words[stats + VGEO_CUT_STAT.QUEUE_REMAINING] > 0
+            || words[stats + VGEO_CUT_STAT.INSTANCES_DROPPED] > 0;
+
+        let taken = 0;
+        let dropped = false;
+
+        for (let i = 0; i < frame.count; i++) {
+            const job = frame.jobs[i];
+            const c = i * VGEO_SDF_COUNTER_WORDS;
+
+            taken += words[c + VGEO_SDF_COUNTER.TAKEN];
+            dropped ||= words[c + VGEO_SDF_COUNTER.DROPPED] > 0;
+
+            if (job.generation !== frame.generations[i]) {
+                // the slot holds another geometry now
+                continue;
+            }
+
+            const complete = !holes
+                && words[c + VGEO_SDF_COUNTER.TAKEN] > 0
+                && words[c + VGEO_SDF_COUNTER.STAND_INS] === 0
+                && words[c + VGEO_SDF_COUNTER.DROPPED] === 0;
+
+            if (frame.decoding[i] === 0) {
+                if (job.phase === JOB_CUT && complete) {
+                    job.vertex_count = words[c + VGEO_SDF_COUNTER.VERTICES];
+                    job.triangle_count = words[c + VGEO_SDF_COUNTER.TRIANGLES];
+                    job.phase = JOB_READY;
+                }
+
+                continue;
+            }
+
+            if (job.phase !== JOB_DECODING) {
+                continue;
+            }
+
+            const whole = complete
+                && words[c + VGEO_SDF_COUNTER.VERTICES] === job.vertex_count
+                && words[c + VGEO_SDF_COUNTER.TRIANGLES] === job.triangle_count
+                && words[c + VGEO_SDF_COUNTER.VERTICES_WRITTEN] === job.vertex_count
+                && words[c + VGEO_SDF_COUNTER.TRIANGLES_WRITTEN] === job.triangle_count;
+
+            if (!whole) {
+                // cut otherwise than the cut its room was made for
+                job.phase = JOB_CUT;
+                continue;
+            }
+
+            const first_vertex = frame.vertex_offset + 3 * frame.vertex_bases[i];
+            const first_index = frame.index_offset + 3 * frame.triangle_bases[i];
+
+            job.positions = new Float32Array(words.buffer, words.byteOffset + 4 * first_vertex, 3 * job.vertex_count).slice();
+            job.indices = words.slice(first_index, first_index + 3 * job.triangle_count);
+            job.phase = JOB_BUILD;
+        }
+
+        if (dropped) {
+            while (this.#cluster_capacity < taken) {
+                this.#cluster_capacity *= 2;
+            }
+        }
+    }
+
+    /**
+     * A frame whose readback was lost: the jobs it wrote out are cut again.
+     *
+     * @param {VGeoSDFFrame} frame
+     */
+    #lose(frame) {
+        for (let i = 0; i < frame.count; i++) {
+            const job = frame.jobs[i];
+
+            if (frame.decoding[i] === 1 && job.generation === frame.generations[i] && job.phase === JOB_DECODING) {
+                job.phase = JOB_CUT;
+            }
+        }
+    }
+
+    destroy() {
+        if (this.#destroyed) {
+            return;
+        }
+
+        this.#destroyed = true;
+
+        const sdf = this.#sdf;
+
+        sdf.remove_source(this);
+        sdf.onRequested.remove(this.#requested_one, this);
+        sdf.onBaked.remove(this.#baked, this);
+
+        for (const job of this.#jobs) {
+            this.#free(job);
+        }
+
+        this.#requested.length = 0;
+
+        this.#cut.destroy();
+        this.#jobs_buffer.destroy();
+    }
+}