@woosh/meep-engine 3.27.0 → 3.28.0

package/src/shade/playground/vgeo_viewer/select_cut.js

@@ -1,481 +0,0 @@
-import { assert } from "../../../core/assert.js";
-import { DEG_TO_RAD } from "../../../core/math/DEG_TO_RAD.js";
-import {
-    VGeoPageWant
-} from "../../renderer/geometry/virtual/format/read/VGeoPageWant.js";
-import { VGEO_NO_CHILD } from "../../renderer/geometry/virtual/format/cluster/VGEO_NO_CHILD.js";
-import { VGEO_SAME_PAGE } from "../../renderer/geometry/virtual/format/cluster/VGEO_SAME_PAGE.js";
-
-/**
- * Selecting a cut from a partially resident container.
- *
- * The traversal itself is the runtime's rule, not a debug approximation of it: descend the page
- * graph from the root's parentless groups, refine a cluster whose error projects above τ, take it
- * when it does not. What this file adds is the part a whole-file reader never has to think about —
- * what to do when the page a refinement wants is not here.
- *
- * The answer is the format's (`VGEO_FORMAT.md` §10): **draw the coarser cluster and say so**. The
- * result is a genuine surface — watertight, correct, merely coarser in that region — and the want it
- * records carries the exact byte range that would refine it. That is what makes streaming safe in
- * any arrival order, and it is why this file's most interesting number is `clamped`.
- *
- * "Not here" is `VGeoContainerReader.is_selectable`, not `is_resident`, and the difference is the
- * one thing about this traversal that is not obvious: a group is refined into only once every page
- * holding one of its *parents* is installed. Residency alone lets a group be entered through the
- * parents that arrived while a coarse cluster still covers the one that did not, and then both are
- * drawn over the same surface. §10 calls that out by name — "no holes **and no double-draw**, in any
- * arrival order" — and the second half is the one that fails silently.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-
-/**
- * The view a cut is selected for. `VIRTUAL_GEOMETRY_DESIGN.md` §4: a cut is selected at one camera's
- * distances and pixel budget, and is the wrong cut for any other.
- */
-export class VGeoCutView {
-    /**
-     * Camera position, object space — the viewer draws at identity, so world and object agree.
-     * @type {Float32Array}
-     */
-    eye = new Float32Array(3);
-
-    /**
-     * Pixels of permitted error. The one quality dial.
-     * @type {number}
-     */
-    tau = 1;
-
-    /**
-     * Height of the render target, in pixels — the projection's numerator.
-     * @type {number}
-     */
-    screen_height = 1080;
-
-    /**
-     * @type {number}
-     */
-    fov_y = 60 * DEG_TO_RAD;
-
-    /**
-     * @type {boolean}
-     */
-    cull_enabled = false;
-
-    /**
-     * Six normalized world-space planes, as {@link Camera.frustum} holds them.
-     * @type {Float32Array}
-     */
-    frustum = new Float32Array(24);
-}
-
-/**
- * What one traversal came to, including what it had to look at to get there and what it could not
- * reach.
- *
- * A cut holds the {@link VGeoPage} objects it selected from rather than page indices, so it stays
- * drawable across an eviction: the bytes it needs are reachable from the cut itself. Nothing here
- * goes stale because residency moved under it.
- */
-export class VGeoCut {
-    /**
-     * The page each selected cluster came from, parallel to {@link clusters}.
-     * @type {VGeoPage[]}
-     */
-    pages = [];
-
-    /**
-     * Selected clusters, as indices within the page at the same position of {@link pages}. There is
-     * no global cluster id in the format and none in the reader; a cluster is a page and an index.
-     * @type {number[]}
-     */
-    clusters = [];
-
-    /**
-     * @type {number}
-     */
-    triangle_count = 0;
-
-    /**
-     * @type {number}
-     */
-    vertex_count = 0;
-
-    /**
-     * @type {number}
-     */
-    groups_visited = 0;
-
-    /**
-     * @type {number}
-     */
-    clusters_tested = 0;
-
-    /**
-     * Clusters whose subtree the frustum threw away, which is a whole region rather than one
-     * cluster — the reason culling belongs in the traversal and not after it.
-     * @type {number}
-     */
-    culled = 0;
-
-    /**
-     * Clusters that projected above τ and were drawn anyway, because the page holding their
-     * refinement is not resident.
-     *
-     * **This is the number that says a cut is still arriving.** Zero means the cut on screen is the
-     * one the container's own metric selects for this view; anything above it means part of the
-     * surface is standing in for something finer, and {@link wants} says exactly what to fetch to
-     * fix it.
-     *
-     * @type {number}
-     */
-    clamped = 0;
-
-    /**
-     * Of those, the ones whose child group's page is **here** and merely not selectable yet, because
-     * a page holding one of that group's other parents is not.
-     *
-     * They carry no want: there is nothing to fetch from a cluster that already has the bytes it
-     * points at. What unblocks them is elsewhere in the same cut — the cluster clamped directly
-     * against the missing page — so this number is not a second streaming frontier, it is how much
-     * of the coarseness on screen is the ancestor rule holding a group back rather than bandwidth.
-     *
-     * @type {number}
-     */
-    clamped_on_activation = 0;
-
-    /**
-     * Which clusters those were, keyed `page · 65536 + cluster`. What the panel counts, a display
-     * can paint — so the regions still waiting on bytes are visible as regions.
-     * @type {Set<number>}
-     */
-    clamped_keys = new Set();
-
-    /**
-     * Clusters whose `child_ref` names an entry outside their page's child table.
-     *
-     * Impossible in a file the validator accepts, and reachable here precisely because validation is
-     * off by default — so it is counted and the cluster is drawn as a leaf, rather than read out of
-     * bounds or thrown out of a traversal that was two thirds of the way to a picture.
-     *
-     * @type {number}
-     */
-    broken_child_refs = 0;
-
-    /**
-     * The pages this cut would need to stop being clamped, one entry per page, most wanted first.
-     * @type {VGeoPageWant[]}
-     */
-    wants = [];
-
-    /**
-     * Distinct pages the traversal read from.
-     * @type {number}
-     */
-    pages_touched = 0;
-
-    /**
-     * @type {number}
-     */
-    duration_ms = 0;
-}
-
-/**
- * `VIRTUAL_GEOMETRY_DESIGN.md` §4: `err_px = r_e · screen_height / (2 · tan(fov_y / 2) · d)`, with
- * `d` the distance to the *closest point* of the sphere.
- *
- * A zero error projects to zero unconditionally — otherwise a leaf, whose error is exactly zero,
- * would become undrawable the moment the camera entered its sphere.
- *
- * @param {number} error object-space `r_e`; `+Infinity` for a root's parent
- * @param {Float32Array} spheres
- * @param {number} base index of the sphere's first component
- * @param {Float32Array} eye
- * @param {number} k `screen_height / (2 · tan(fov_y / 2))`, hoisted out of the loop
- * @returns {number} pixels
- */
-function project_error(error, spheres, base, eye, k) {
-    if (error === 0) {
-        return 0;
-    }
-
-    const dx = eye[0] - spheres[base];
-    const dy = eye[1] - spheres[base + 1];
-    const dz = eye[2] - spheres[base + 2];
-
-    const distance = Math.sqrt(dx * dx + dy * dy + dz * dz) - spheres[base + 3];
-
-    if (distance <= 0) {
-        // camera inside the sphere; the projection is unbounded and the cluster must refine
-        return Number.POSITIVE_INFINITY;
-    }
-
-    return (error * k) / distance;
-}
-
-/**
- * Whether a sphere is entirely outside the frustum.
- *
- * Only the five finite planes are tested. The projection is infinite reverse-Z, so the far plane's
- * row is degenerate and normalizing it produces nothing a test can use.
- *
- * @param {Float32Array} frustum
- * @param {Float32Array} spheres
- * @param {number} base
- * @returns {boolean}
- */
-function sphere_outside_frustum(frustum, spheres, base) {
-    const x = spheres[base];
-    const y = spheres[base + 1];
-    const z = spheres[base + 2];
-    const radius = spheres[base + 3];
-
-    for (let plane = 0; plane < 5; plane++) {
-        const o = plane * 4;
-
-        const distance = frustum[o] * x + frustum[o + 1] * y + frustum[o + 2] * z + frustum[o + 3];
-
-        if (distance < -radius) {
-            return true;
-        }
-    }
-
-    return false;
-}
-
-/**
- * Select the cut for a view from whatever the reader currently holds.
- *
- * A traversal rather than a flat pass over every cluster, per design §4 — and it gets the cut rule's
- * first half for free. The rule is `project(parent) > τ AND project(self) ≤ τ`; a group is only ever
- * reached by descending *through* the cluster whose step consumed it, and that descent happened
- * precisely because the step projected above τ. Every cluster of a group shares that step's sphere
- * and error, so the parent test is satisfied by the act of arriving.
- *
- * The residency clamp is the live one here, and it is the reason a cut can be taken at all before
- * the file has finished arriving: a cluster that wants a page nobody has is drawn as it stands.
- *
- * @param {VGeoContainerReader} reader
- * @param {VGeoCutView} view
- * @returns {VGeoCut}
- */
-export function vgeo_select_cut(reader, view) {
-    assert.defined(reader.root, 'reader.root — the container must be open');
-
-    const started = performance.now();
-
-    const cut = new VGeoCut();
-
-    const k = view.screen_height / (2 * Math.tan(view.fov_y * 0.5));
-
-    /**
-     * Groups already queued, keyed `page · 65536 + group`. A group is referenced by every sibling
-     * cluster of the step that consumed it, so without this the traversal would expand it once per
-     * parent and the cut would carry duplicates.
-     *
-     * Multiplied rather than shifted: a page index is a u32, and `<<` would wrap it at the sixteenth
-     * page of a large asset.
-     *
-     * @type {Set<number>}
-     */
-    const queued = new Set();
-
-    /**
-     * @type {Set<number>}
-     */
-    const touched = new Set();
-
-    /**
-     * Wants by page index, so that many clamped clusters wanting one page produce one entry — which
-     * is also where {@link VGeoPageWant.reference_count} comes from.
-     * @type {Map<number, VGeoPageWant>}
-     */
-    const wants = new Map();
-
-    /**
-     * Page and group index, interleaved.
-     * @type {number[]}
-     */
-    const stack = [];
-
-    const root = reader.root;
-
-    for (let group = 0; group < root.group_parent_count.length; group++) {
-        // no cluster anywhere refines into this group, so it is the top of the DAG and selectable
-        // with nothing above it
-        if (root.group_parent_count[group] === 0) {
-            queued.add(group);
-            stack.push(0, group);
-        }
-    }
-
-    while (stack.length > 0) {
-        const group = stack.pop();
-        const page_index = stack.pop();
-
-        const page = reader.page(page_index);
-
-        if (page === undefined) {
-            // Evicted between being queued and being reached. Nothing here fetches, so the subtree
-            // is simply not selected; the clusters above it were already taken by whoever queued it.
-            continue;
-        }
-
-        cut.groups_visited++;
-        touched.add(page_index);
-
-        const first = page.group_cluster_first[group];
-        const count = page.group_cluster_count[group];
-
-        for (let i = 0; i < count; i++) {
-            const id = first + i;
-
-            cut.clusters_tested++;
-
-            /*
-             Culling on `self_sphere` rather than on the tight `bounds_sphere`, because this decides
-             the subtree as well as the cluster: monotonicity makes a cluster's self sphere contain
-             every descendant's geometry, so a self sphere outside the frustum means nothing under
-             it can be on screen either.
-             */
-            if (view.cull_enabled
-                && sphere_outside_frustum(view.frustum, page.self_sphere, id * 4)) {
-                cut.culled++;
-                continue;
-            }
-
-            const child_ref = page.child_ref[id];
-
-            const self_px = project_error(
-                page.self_error[id], page.self_sphere, id * 4, view.eye, k
-            );
-
-            if (self_px <= view.tau || child_ref === VGEO_NO_CHILD) {
-                select(cut, page, id);
-                continue;
-            }
-
-            if (child_ref !== VGEO_SAME_PAGE && child_ref >= page.child_page_index.length) {
-                cut.broken_child_refs++;
-
-                select(cut, page, id);
-                continue;
-            }
-
-            const child_page = child_ref === VGEO_SAME_PAGE
-                ? page_index
-                : page.child_page_index[child_ref];
-
-            const child_group = page.child_group[id];
-
-            /*
-             *Selectable*, not resident — §10, and the difference is the whole of this file's
-             correctness. A group's parents are made by one simplification step but grouped for the
-             next one separately, so they can end up in different pages; refining into a group
-             because its own page arrived, while a page holding one of its other parents has not,
-             draws it underneath the coarse cluster still standing in for that parent. Both cover the
-             same surface and the depth buffer picks between them at random. `is_selectable` is the
-             counter that says the group's entire ancestor cone is here.
-
-             `SAME_PAGE` is asked the same question. Being in this page settles where the bytes are
-             and nothing about where the group's other parents live.
-             */
-            if (reader.is_selectable(child_page, child_group)) {
-                push(stack, queued, child_page, child_group);
-                continue;
-            }
-
-            /*
-             The clamp. Drawing this cluster is not a fallback for a missing one — it is the correct
-             coarser surface over exactly the region the missing page would have refined, which is
-             what makes an arriving cut watertight at every moment rather than only at the end.
-             */
-            cut.clamped++;
-            cut.clamped_keys.add(page_index * 65536 + id);
-
-            select(cut, page, id);
-
-            if (reader.is_resident(child_page)) {
-                /*
-                 §10: a want naming a page that is already installed is an activation recheck, never
-                 a fetch. There is nothing to ask for *here* — what this group is waiting on is a
-                 page holding one of its other parents, and the format stores parent counts rather
-                 than parent references precisely so that nobody has to name it. Another cluster in
-                 this same traversal is clamped directly against that page and wants it, because
-                 monotonicity puts every ancestor of a cluster projecting above τ above τ as well.
-                 */
-                cut.clamped_on_activation++;
-                continue;
-            }
-
-            want(wants, page, child_ref, child_page, self_px);
-        }
-    }
-
-    cut.wants = Array.from(wants.values()).sort((a, b) => b.priority - a.priority);
-    cut.pages_touched = touched.size;
-    cut.duration_ms = performance.now() - started;
-
-    return cut;
-}
-
-/**
- * @param {VGeoCut} cut
- * @param {VGeoPage} page
- * @param {number} cluster index within `page`
- */
-function select(cut, page, cluster) {
-    cut.pages.push(page);
-    cut.clusters.push(cluster);
-
-    cut.triangle_count += page.triangle_count[cluster];
-    cut.vertex_count += page.vertex_count[cluster];
-}
-
-/**
- * @param {number[]} stack
- * @param {Set<number>} queued
- * @param {number} page_index
- * @param {number} group
- */
-function push(stack, queued, page_index, group) {
-    const key = page_index * 65536 + group;
-
-    if (queued.has(key)) {
-        return;
-    }
-
-    queued.add(key);
-    stack.push(page_index, group);
-}
-
-/**
- * Record — or reinforce — a want for the page a clamped cluster could not reach.
- *
- * Everything the fetch needs comes out of the child table of the page that is already here, which is
- * the property (§5) that lets refinement cost one round trip and no metadata request.
- *
- * @param {Map<number, VGeoPageWant>} wants
- * @param {VGeoPage} page the resident page holding the clamped cluster
- * @param {number} child_ref index into that page's child table
- * @param {number} child_page
- * @param {number} projected pixels the clamped cluster's error came to
- */
-function want(wants, page, child_ref, child_page, projected) {
-    let record = wants.get(child_page);
-
-    if (record === undefined) {
-        record = new VGeoPageWant();
-
-        record.page_index = child_page;
-        record.frame_offset = page.child_frame_offset[child_ref];
-        record.fetch_size = page.child_fetch_size[child_ref];
-        record.decoded_size = page.child_decoded_size[child_ref];
-
-        wants.set(child_page, record);
-    }
-
-    record.reference_count++;
-    record.priority = Math.max(record.priority, projected);
-}