@woosh/meep-engine 3.20.0 → 3.21.0

package/src/shade/renderer/geometry/virtual/format/read/VGeoContainerHeader.d.ts

@@ -0,0 +1,122 @@
+/**
+ * A `.vgeo` file's header and level table, decoded — the first 256 bytes plus `32 · level_count`
+ * after them, and nothing else.
+ *
+ * This is everything a reader knows before it has fetched a single page, and it is deliberately
+ * enough to be useful on its own: how big the asset is, how many pages and clusters it will come to,
+ * where its root frame sits and how large it is, and — through {@link levels} — what error each band
+ * carries, which is what lets an instance's level range be bracketed without touching geometry
+ * (`VGEO_FORMAT.md` §4.1).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoContainerHeader {
+    /**
+     * @type {number}
+     */
+    format_version: number;
+    /**
+     * The lowest reader version the file will read correctly under. A reader below it must refuse
+     * the file rather than read it, per §4.
+     * @type {number}
+     */
+    min_reader_version: number;
+    /**
+     * @type {number}
+     */
+    payload_encoding: number;
+    /**
+     * Hex, as the 16 asset-id bytes stand in the file. In a streamed deployment this is also the
+     * file's name, which is what makes same-URL version skew impossible.
+     * @type {string}
+     */
+    asset_id: string;
+    /**
+     * The low 64 bits of {@link asset_id}, which is the seed every frame checksum is taken under
+     * (§5). Kept as its own field because that is the only thing it is for, and deriving it from the
+     * hex string at each frame would be absurd.
+     * @type {bigint}
+     */
+    asset_id_low64: bigint;
+    /**
+     * Advisory: which attributes the payloads carry. Advisory because the authority is each
+     * cluster's own `encoding_flags`.
+     * @type {number}
+     */
+    vertex_attribute_mask: number;
+    /**
+     * @type {number}
+     */
+    total_pages: number;
+    /**
+     * @type {number}
+     */
+    total_clusters: number;
+    /**
+     * @type {number}
+     */
+    total_groups: number;
+    /**
+     * Absolute offset of the root page's frame, which is also the end of the level table.
+     * @type {number}
+     */
+    root_page_offset: number;
+    /**
+     * The exact byte range the root frame occupies, so the always-resident set can be fetched from
+     * the header alone.
+     * @type {number}
+     */
+    root_page_fetch_size: number;
+    /**
+     * What the root page costs decoded — RAM admission before a byte of it is fetched.
+     * @type {number}
+     */
+    root_page_decoded_size: number;
+    /**
+     * Absolute offset of the page directory, which is also the exact end of the frame region.
+     * @type {number}
+     */
+    directory_offset: number;
+    /**
+     * @type {number}
+     */
+    dir_block_checksums_offset: number;
+    /**
+     * The build parameter, informational. A reader must never assume it: per-page sizes come from
+     * child tables, frames, or the directory.
+     * @type {number}
+     */
+    nominal_page_size: number;
+    /**
+     * Vertices of the normalized source mesh the leaves stand for.
+     * @type {number}
+     */
+    source_vertex_count: number;
+    /**
+     * @type {number}
+     */
+    source_face_count: number;
+    /**
+     * Object-space bounding sphere of the whole geometry: centre xyz then radius.
+     * @type {Float32Array}
+     */
+    object_sphere: Float32Array;
+    /**
+     * Object-space AABB: min xyz then max xyz.
+     * @type {Float32Array}
+     */
+    object_bounds: Float32Array;
+    /**
+     * One row per level, coarsest last — the table at `256 + 32·i`.
+     * @type {VGeoLevelRecord[]}
+     */
+    levels: VGeoLevelRecord[];
+    /**
+     * How many bytes the header and its level table occupy together, which is where the root frame
+     * begins for every file the writer produces.
+     * @returns {number}
+     */
+    get head_size(): number;
+}
+//# sourceMappingURL=VGeoContainerHeader.d.ts.map

package/src/shade/renderer/geometry/virtual/format/read/VGeoContainerHeader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VGeoContainerHeader.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/VGeoContainerHeader.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH;IACI;;OAEG;IACH,gBAFU,MAAM,CAEG;IAEnB;;;;OAIG;IACH,oBAFU,MAAM,CAEO;IAEvB;;OAEG;IACH,kBAFU,MAAM,CAEK;IAErB;;;;OAIG;IACH,UAFU,MAAM,CAEF;IAEd;;;;;OAKG;IACH,gBAFU,MAAM,CAEI;IAEpB;;;;OAIG;IACH,uBAFU,MAAM,CAEU;IAE1B;;OAEG;IACH,aAFU,MAAM,CAEA;IAEhB;;OAEG;IACH,gBAFU,MAAM,CAEG;IAEnB;;OAEG;IACH,cAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,kBAFU,MAAM,CAEK;IAErB;;;;OAIG;IACH,sBAFU,MAAM,CAES;IAEzB;;;OAGG;IACH,wBAFU,MAAM,CAEW;IAE3B;;;OAGG;IACH,kBAFU,MAAM,CAEK;IAErB;;OAEG;IACH,4BAFU,MAAM,CAEe;IAE/B;;;;OAIG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,qBAFU,MAAM,CAEQ;IAExB;;OAEG;IACH,mBAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,eAFU,YAAY,CAEc;IAEpC;;;OAGG;IACH,QAFU,iBAAiB,CAEf;IAEZ;;;;OAIG;IACH,wBAEC;CACJ"}

package/src/shade/renderer/geometry/virtual/format/read/VGeoContainerHeader.js

@@ -0,0 +1,143 @@
+/**
+ * A `.vgeo` file's header and level table, decoded — the first 256 bytes plus `32 · level_count`
+ * after them, and nothing else.
+ *
+ * This is everything a reader knows before it has fetched a single page, and it is deliberately
+ * enough to be useful on its own: how big the asset is, how many pages and clusters it will come to,
+ * where its root frame sits and how large it is, and — through {@link levels} — what error each band
+ * carries, which is what lets an instance's level range be bracketed without touching geometry
+ * (`VGEO_FORMAT.md` §4.1).
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoContainerHeader {
+    /**
+     * @type {number}
+     */
+    format_version = 0;
+
+    /**
+     * The lowest reader version the file will read correctly under. A reader below it must refuse
+     * the file rather than read it, per §4.
+     * @type {number}
+     */
+    min_reader_version = 0;
+
+    /**
+     * @type {number}
+     */
+    payload_encoding = 0;
+
+    /**
+     * Hex, as the 16 asset-id bytes stand in the file. In a streamed deployment this is also the
+     * file's name, which is what makes same-URL version skew impossible.
+     * @type {string}
+     */
+    asset_id = '';
+
+    /**
+     * The low 64 bits of {@link asset_id}, which is the seed every frame checksum is taken under
+     * (§5). Kept as its own field because that is the only thing it is for, and deriving it from the
+     * hex string at each frame would be absurd.
+     * @type {bigint}
+     */
+    asset_id_low64 = 0n;
+
+    /**
+     * Advisory: which attributes the payloads carry. Advisory because the authority is each
+     * cluster's own `encoding_flags`.
+     * @type {number}
+     */
+    vertex_attribute_mask = 0;
+
+    /**
+     * @type {number}
+     */
+    total_pages = 0;
+
+    /**
+     * @type {number}
+     */
+    total_clusters = 0;
+
+    /**
+     * @type {number}
+     */
+    total_groups = 0;
+
+    /**
+     * Absolute offset of the root page's frame, which is also the end of the level table.
+     * @type {number}
+     */
+    root_page_offset = 0;
+
+    /**
+     * The exact byte range the root frame occupies, so the always-resident set can be fetched from
+     * the header alone.
+     * @type {number}
+     */
+    root_page_fetch_size = 0;
+
+    /**
+     * What the root page costs decoded — RAM admission before a byte of it is fetched.
+     * @type {number}
+     */
+    root_page_decoded_size = 0;
+
+    /**
+     * Absolute offset of the page directory, which is also the exact end of the frame region.
+     * @type {number}
+     */
+    directory_offset = 0;
+
+    /**
+     * @type {number}
+     */
+    dir_block_checksums_offset = 0;
+
+    /**
+     * The build parameter, informational. A reader must never assume it: per-page sizes come from
+     * child tables, frames, or the directory.
+     * @type {number}
+     */
+    nominal_page_size = 0;
+
+    /**
+     * Vertices of the normalized source mesh the leaves stand for.
+     * @type {number}
+     */
+    source_vertex_count = 0;
+
+    /**
+     * @type {number}
+     */
+    source_face_count = 0;
+
+    /**
+     * Object-space bounding sphere of the whole geometry: centre xyz then radius.
+     * @type {Float32Array}
+     */
+    object_sphere = new Float32Array(4);
+
+    /**
+     * Object-space AABB: min xyz then max xyz.
+     * @type {Float32Array}
+     */
+    object_bounds = new Float32Array(6);
+
+    /**
+     * One row per level, coarsest last — the table at `256 + 32·i`.
+     * @type {VGeoLevelRecord[]}
+     */
+    levels = [];
+
+    /**
+     * How many bytes the header and its level table occupy together, which is where the root frame
+     * begins for every file the writer produces.
+     * @returns {number}
+     */
+    get head_size() {
+        return this.root_page_offset;
+    }
+}

package/src/shade/renderer/geometry/virtual/format/read/VGeoContainerReader.d.ts

@@ -0,0 +1,185 @@
+/**
+ * A `.vgeo` container, read a page at a time.
+ *
+ * **Nothing here ever holds the whole file.** Opening it reads a head prefix — the header, the level
+ * table, and the root frame, which §10 calls the always-resident set — and after that a page arrives
+ * only when something asks for it, from exactly the byte range the page pointing at it wrote down.
+ * That is not an optimization bolted onto a whole-file reader; it is the shape the format was
+ * designed for, and a reader built the other way cannot be made into this one.
+ *
+ * What that buys, concretely: a 27-million-triangle asset opens in the bytes of its root page, and a
+ * view of it costs the pages that view actually selects. What it costs is that a traversal has to
+ * cope with a page it wants and does not have — which the format also already answers, because the
+ * clamped cut is watertight and correct at every arrival order (§10, activation).
+ *
+ * Residency is this object. {@link page} answers for what is here, {@link install_want} brings one
+ * more, {@link evict} drops one, and a {@link VGeoPage} owns its own bytes and tables so that
+ * dropping it drops everything it cost.
+ *
+ * **Validation is not on this path.** The mandatory reject rules of §4 and §10 are applied
+ * unconditionally by {@link vgeo_read_header} and {@link vgeo_read_page} — a file whose magic,
+ * versions, encoding or codec this build does not understand is refused rather than misread. The
+ * whole-file audit is {@link validate}, it reads every byte of the file, and it is off by default;
+ * see {@link VGeoReadOptions.validate}.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class VGeoContainerReader {
+    /**
+     * Open a container: header, level table, root page.
+     *
+     * @param {VGeoByteSource} source
+     * @param {VGeoReadOptions} [options]
+     * @returns {Promise<VGeoContainerReader>}
+     * @throws {Error} when the bytes are not a `.vgeo` this build reads, or the root frame does not
+     *     match what the header says about it
+     */
+    static open(source: VGeoByteSource, options?: VGeoReadOptions): Promise<VGeoContainerReader>;
+    /**
+     * @param {VGeoByteSource} source
+     * @param {VGeoReadOptions} [options]
+     */
+    constructor(source: VGeoByteSource, options?: VGeoReadOptions);
+    /**
+     * @type {VGeoContainerHeader}
+     */
+    header: VGeoContainerHeader;
+    /**
+     * The page directory, once {@link read_directory} has been asked for it. A traversal never needs
+     * it; a tool looking at every page does.
+     * @type {VGeoDirectory|undefined}
+     */
+    directory: VGeoDirectory | undefined;
+    /**
+     * @returns {VGeoByteSource}
+     */
+    get source(): VGeoByteSource;
+    /**
+     * @returns {VGeoReadOptions}
+     */
+    get options(): VGeoReadOptions;
+    /**
+     * @returns {number}
+     */
+    get resident_page_count(): number;
+    /**
+     * Decoded bytes currently held. The number a residency budget is spent against.
+     * @returns {number}
+     */
+    get resident_bytes(): number;
+    /**
+     * @returns {number}
+     */
+    get pending_page_count(): number;
+    /**
+     * The root page, which is pinned for the life of the reader — §10 makes it the one page that is
+     * never evictable, because every traversal starts by walking its parentless groups.
+     * @returns {VGeoPage}
+     */
+    get root(): VGeoPage;
+    /**
+     * Every resident page, in page-index order.
+     * @returns {VGeoPage[]}
+     */
+    get pages(): VGeoPage[];
+    /**
+     * The page, if it is here.
+     *
+     * Synchronous and total: a traversal asks this per cluster and must not await inside itself, so
+     * `undefined` is an answer it acts on — clamp, and record a want — rather than a case to handle.
+     *
+     * @param {number} page_index
+     * @returns {VGeoPage|undefined}
+     */
+    page(page_index: number): VGeoPage | undefined;
+    /**
+     * @param {number} page_index
+     * @returns {boolean}
+     */
+    is_resident(page_index: number): boolean;
+    /**
+     * Fetch and install one page, from the exact range something already resident named.
+     *
+     * Concurrent calls for the same page share one fetch; a page already resident is returned
+     * without one.
+     *
+     * @param {number} page_index
+     * @param {number} frame_offset absolute
+     * @param {number} fetch_size
+     * @returns {Promise<VGeoPage>}
+     */
+    install(page_index: number, frame_offset: number, fetch_size: number): Promise<VGeoPage>;
+    /**
+     * Install the page a want names.
+     *
+     * @param {VGeoPageWant} want
+     * @returns {Promise<VGeoPage>}
+     */
+    install_want(want: VGeoPageWant): Promise<VGeoPage>;
+    /**
+     * Install a batch of wants, most wanted first, with a bounded number of fetches in flight.
+     *
+     * Ordered by {@link VGeoPageWant.priority}, which is how far past the pixel threshold the
+     * clamped cluster projected — so a caller that stops early has fetched the pages that would fix
+     * the most visible coarseness, not an arbitrary prefix of the list.
+     *
+     * @param {VGeoPageWant[]} wants
+     * @param {number} [limit] most pages to install; the rest are left for the next traversal to
+     *     want again, which it will, from a cut taken with everything this call did install
+     * @returns {Promise<VGeoPage[]>} the pages installed, in completion order
+     */
+    install_wants(wants: VGeoPageWant[], limit?: number): Promise<VGeoPage[]>;
+    /**
+     * Drop a page.
+     *
+     * The eviction *rule* — a page is evictable only while it has no resident child pages, and the
+     * root is pinned (§10) — is a residency policy and belongs to whatever is managing the budget,
+     * not here. What this does is the dropping.
+     *
+     * @param {number} page_index
+     * @returns {boolean} whether a page was there to drop
+     */
+    evict(page_index: number): boolean;
+    /**
+     * Drop every page but the root, which is pinned.
+     *
+     * @returns {number} pages dropped
+     */
+    evict_all(): number;
+    /**
+     * Read the page directory, and keep it on {@link directory}.
+     *
+     * One fetch of a region that is 32 bytes per page — a hundred kilobytes for a file with three
+     * thousand pages. Auxiliary by design: nothing a traversal does needs it, and asking for it says
+     * the caller wants to reach pages the DAG does not lead it to.
+     *
+     * @returns {Promise<VGeoDirectory>}
+     */
+    read_directory(): Promise<VGeoDirectory>;
+    /**
+     * Install every page the directory lists.
+     *
+     * The opposite of what this reader is for, and exactly what a tool wants when the question is
+     * about the file rather than about a view of it — the pages no cut reaches are the ones a bug
+     * hides in.
+     *
+     * @param {function(number, number): void} [on_progress] called with pages installed and total
+     * @returns {Promise<void>}
+     */
+    install_all_pages(on_progress?: (arg0: number, arg1: number) => void): Promise<void>;
+    /**
+     * The whole-file audit — every build invariant of §11, every checksum, and the directory against
+     * what a frame scan reconstructs.
+     *
+     * **This reads the entire file**, which is the one thing the rest of this class exists to avoid,
+     * and it is why it is a separate call and off by default. It answers a question about whoever
+     * produced the file; nothing about reading one depends on it having been asked.
+     *
+     * @returns {Promise<VGeoDefect[]>} empty is the only good answer
+     */
+    validate(): Promise<VGeoDefect[]>;
+    #private;
+}
+import { VGeoReadOptions } from "./VGeoReadOptions.js";
+//# sourceMappingURL=VGeoContainerReader.d.ts.map

package/src/shade/renderer/geometry/virtual/format/read/VGeoContainerReader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"VGeoContainerReader.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/geometry/virtual/format/read/VGeoContainerReader.js"],"names":[],"mappings":"AAiBA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IAqHI;;;;;;;;OAQG;IACH,8CALW,eAAe,GACb,QAAQ,mBAAmB,CAAC,CAUxC;IA/ED;;;OAGG;IACH,8CAFW,eAAe,EAOzB;IA7DD;;OAEG;IACH,4BAAmB;IAEnB;;;;OAIG;IACH,WAFU,gBAAc,SAAS,CAEX;IAqDtB;;OAEG;IACH,6BAEC;IAED;;OAEG;IACH,+BAEC;IAED;;OAEG;IACH,kCAEC;IAED;;;OAGG;IACH,6BAEC;IAED;;OAEG;IACH,iCAEC;IAED;;;;OAIG;IACH,qBAEC;IAED;;;OAGG;IACH,wBAEC;IAyFD;;;;;;;;OAQG;IACH,iBAHW,MAAM,GACJ,WAAS,SAAS,CAI9B;IAED;;;OAGG;IACH,wBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;;OAUG;IACH,oBALW,MAAM,gBACN,MAAM,cACN,MAAM,GACJ,iBAAiB,CAqB7B;IA+BD;;;;;OAKG;IACH,kCAFa,iBAAiB,CAI7B;IAED;;;;;;;;;;;OAWG;IACH,qBALW,cAAc,UACd,MAAM,GAEJ,QAAQ,UAAU,CAAC,CA8B/B;IAED;;;;;;;;;OASG;IACH,kBAHW,MAAM,GACJ,OAAO,CAcnB;IAED;;;;OAIG;IACH,aAFa,MAAM,CAYlB;IAED;;;;;;;;OAQG;IACH,kBAFa,sBAAsB,CAkBlC;IAED;;;;;;;;;OASG;IACH,uCAHoB,MAAM,QAAE,MAAM,KAAG,IAAI,GAC5B,QAAQ,IAAI,CAAC,CAgBzB;IAED;;;;;;;;;OASG;IACH,YAFa,QAAQ,YAAY,CAAC,CAUjC;;CA6EJ;gCArjB+B,sBAAsB"}