@woosh/meep-engine 3.20.0 → 3.21.0

package/src/shade/playground/vgeo_viewer/sample_asset.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Build a sample container and hand back a source over it.
+ *
+ * The page size is deliberately far below the 256 KB default: a sample that came out as one page
+ * would be a container with nothing to stream, and the point of opening this one is to watch it
+ * arrive.
+ *
+ * @param {number} [major]
+ * @param {number} [minor]
+ * @param {number} [page_size] target decoded bytes per page
+ * @returns {{source: VGeoByteSource, build_ms: number}}
+ */
+export function vgeo_sample_source(major?: number, minor?: number, page_size?: number): {
+    source: VGeoByteSource;
+    build_ms: number;
+};
+import { VGeoByteSource } from "../../renderer/geometry/virtual/format/read/VGeoByteSource.js";
+//# sourceMappingURL=sample_asset.d.ts.map

package/src/shade/playground/vgeo_viewer/sample_asset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sample_asset.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/vgeo_viewer/sample_asset.js"],"names":[],"mappings":"AAyFA;;;;;;;;;;;GAWG;AACH,2CALW,MAAM,UACN,MAAM,cACN,MAAM,GACJ;IAAC,MAAM,EAAE,cAAc,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAC,CAiBtD;+BAzGM,+DAA+D"}

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

@@ -0,0 +1,117 @@
+import { BinaryDataType } from "../../../core/binary/type/BinaryDataType.js";
+import { AttributeSpec } from "../../../engine/graphics/geometry/AttributeSpec.js";
+import { Attribute } from "../../renderer/geometry/Attribute.js";
+import { Geometry } from "../../renderer/geometry/Geometry.js";
+import { StandardAttributes } from "../../renderer/geometry/StandardAttributes.js";
+import { vgeo_build } from "../../renderer/geometry/virtual/build/vgeo_build.js";
+import {
+    VGeoBuildOptions
+} from "../../renderer/geometry/virtual/build/VGeoBuildOptions.js";
+import {
+    VGeoByteSource
+} from "../../renderer/geometry/virtual/format/read/VGeoByteSource.js";
+
+/**
+ * A `.vgeo` built in the page, so the viewer has something to open without a file.
+ *
+ * The builder is environment-agnostic by design (`VIRTUAL_GEOMETRY_DESIGN.md` §8) — typed arrays and
+ * topology, no file or process API anywhere under it — so the same call the node CLI makes runs here.
+ * What comes out is a real container: real frames, real child tables, real checksums, and the reader
+ * opens it through exactly the interface it would open a URL through.
+ *
+ * Small on purpose. This is what makes the page work the moment it loads and what makes it
+ * verifiable without an asset in the tree; a file worth actually looking at comes off disk.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/**
+ * A torus — closed, curved everywhere, and cheap to build.
+ *
+ * Curvature is what makes it a useful sample rather than a shape: a flat face simplifies at zero
+ * quadric cost, so a box would produce a DAG whose every step records no error and whose every
+ * threshold selects the same cut. A torus has an error at every level, which is the thing the viewer
+ * is drawing.
+ *
+ * @param {number} major segments the long way round
+ * @param {number} minor segments around the tube
+ * @returns {Geometry}
+ */
+function torus(major, minor) {
+    const positions = [];
+    const indices = [];
+
+    for (let i = 0; i <= major; i++) {
+        const u = i / major * Math.PI * 2;
+
+        for (let j = 0; j <= minor; j++) {
+            const v = j / minor * Math.PI * 2;
+
+            const radius = 1 + 0.35 * Math.cos(v);
+
+            positions.push(radius * Math.cos(u), 0.35 * Math.sin(v), radius * Math.sin(u));
+        }
+    }
+
+    const stride = minor + 1;
+
+    for (let i = 0; i < major; i++) {
+        for (let j = 0; j < minor; j++) {
+            const a = i * stride + j;
+            const b = a + stride;
+
+            indices.push(a, b, a + 1);
+            indices.push(a + 1, b, b + 1);
+        }
+    }
+
+    const geometry = new Geometry();
+
+    const position = new Attribute();
+
+    position.spec = AttributeSpec.from(BinaryDataType.Float32, 3, false, StandardAttributes.Position);
+    position.data = Float32Array.from(positions);
+    position.count = positions.length / 3;
+
+    geometry.addAttribute(position);
+
+    const index = new Attribute();
+
+    index.spec = AttributeSpec.from(BinaryDataType.Uint32, 1, false, 'index');
+    index.data = Uint32Array.from(indices);
+    index.count = indices.length;
+
+    geometry.index = index;
+
+    return geometry;
+}
+
+/**
+ * Build a sample container and hand back a source over it.
+ *
+ * The page size is deliberately far below the 256 KB default: a sample that came out as one page
+ * would be a container with nothing to stream, and the point of opening this one is to watch it
+ * arrive.
+ *
+ * @param {number} [major]
+ * @param {number} [minor]
+ * @param {number} [page_size] target decoded bytes per page
+ * @returns {{source: VGeoByteSource, build_ms: number}}
+ */
+export function vgeo_sample_source(major = 128, minor = 48, page_size = 8 * 1024) {
+    const options = new VGeoBuildOptions();
+
+    options.nominal_page_size = page_size;
+
+    const started = performance.now();
+
+    const bytes = vgeo_build(torus(major, minor), options).buffer.raw_bytes;
+
+    const build_ms = performance.now() - started;
+
+    return {
+        source: VGeoByteSource.of(bytes, `torus ${major}×${minor} (built in the page)`),
+        build_ms,
+    };
+}

package/src/shade/playground/vgeo_viewer/select_cut.d.ts

@@ -0,0 +1,154 @@
+/**
+ * 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: VGeoContainerReader, view: VGeoCutView): VGeoCut;
+/**
+ * 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`.
+ *
+ * @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: Float32Array;
+    /**
+     * Pixels of permitted error. The one quality dial.
+     * @type {number}
+     */
+    tau: number;
+    /**
+     * Height of the render target, in pixels — the projection's numerator.
+     * @type {number}
+     */
+    screen_height: number;
+    /**
+     * @type {number}
+     */
+    fov_y: number;
+    /**
+     * @type {boolean}
+     */
+    cull_enabled: boolean;
+    /**
+     * Six normalized world-space planes, as {@link Camera.frustum} holds them.
+     * @type {Float32Array}
+     */
+    frustum: Float32Array;
+}
+/**
+ * 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: VGeoPage[];
+    /**
+     * 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: number[];
+    /**
+     * @type {number}
+     */
+    triangle_count: number;
+    /**
+     * @type {number}
+     */
+    vertex_count: number;
+    /**
+     * @type {number}
+     */
+    groups_visited: number;
+    /**
+     * @type {number}
+     */
+    clusters_tested: number;
+    /**
+     * 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: number;
+    /**
+     * 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: number;
+    /**
+     * 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: Set<number>;
+    /**
+     * 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: number;
+    /**
+     * The pages this cut would need to stop being clamped, one entry per page, most wanted first.
+     * @type {VGeoPageWant[]}
+     */
+    wants: VGeoPageWant[];
+    /**
+     * Distinct pages the traversal read from.
+     * @type {number}
+     */
+    pages_touched: number;
+    /**
+     * @type {number}
+     */
+    duration_ms: number;
+}
+import { VGeoPageWant } from "../../renderer/geometry/virtual/format/read/VGeoPageWant.js";
+//# sourceMappingURL=select_cut.d.ts.map

package/src/shade/playground/vgeo_viewer/select_cut.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"select_cut.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/vgeo_viewer/select_cut.js"],"names":[],"mappings":"AAkOA;;;;;;;;;;;;;;;GAeG;AACH,mEAHW,WAAW,GACT,OAAO,CAwInB;AAhXD;;;;;;;;;;;;;;;GAeG;AAEH;;;GAGG;AACH;IACI;;;OAGG;IACH,KAFU,YAAY,CAEI;IAE1B;;;OAGG;IACH,KAFU,MAAM,CAER;IAER;;;OAGG;IACH,eAFU,MAAM,CAEK;IAErB;;OAEG;IACH,OAFU,MAAM,CAEQ;IAExB;;OAEG;IACH,cAFU,OAAO,CAEI;IAErB;;;OAGG;IACH,SAFU,YAAY,CAES;CAClC;AAED;;;;;;;GAOG;AACH;IACI;;;OAGG;IACH,OAFU,UAAU,CAET;IAEX;;;;OAIG;IACH,UAFU,MAAM,EAAE,CAEJ;IAEd;;OAEG;IACH,gBAFU,MAAM,CAEG;IAEnB;;OAEG;IACH,cAFU,MAAM,CAEC;IAEjB;;OAEG;IACH,gBAFU,MAAM,CAEG;IAEnB;;OAEG;IACH,iBAFU,MAAM,CAEI;IAEpB;;;;OAIG;IACH,QAFU,MAAM,CAEL;IAEX;;;;;;;;;;OAUG;IACH,SAFU,MAAM,CAEJ;IAEZ;;;;OAIG;IACH,cAFU,IAAI,MAAM,CAAC,CAEI;IAEzB;;;;;;;;OAQG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,OAFU,YAAY,EAAE,CAEb;IAEX;;;OAGG;IACH,eAFU,MAAM,CAEE;IAElB;;OAEG;IACH,aAFU,MAAM,CAEA;CACnB;6BA7JM,6DAA6D"}