@woosh/meep-engine 3.26.0 → 3.28.0

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

@@ -10,6 +10,7 @@ import { vgeo_decode_frame_blob } from "../frame/vgeo_decode_frame_blob.js";
 import { VGEO_FRAME_HEADER_SIZE } from "../frame/VGEO_FRAME_HEADER_SIZE.js";
 import { VGEO_FRAME_OFFSET } from "../frame/VGEO_FRAME_OFFSET.js";
 import { vgeo_frame_decode_bound } from "../frame/vgeo_frame_decode_bound.js";
+import { VGEO_GROUP_OFFSET } from "../page/VGEO_GROUP_OFFSET.js";
 import { VGEO_GROUP_RECORD_SIZE } from "../page/VGEO_GROUP_RECORD_SIZE.js";
 import { VGEO_METRIC_OFFSET } from "../page/VGEO_METRIC_OFFSET.js";
 import { VGEO_NODE_OFFSET } from "../page/VGEO_NODE_OFFSET.js";
@@ -17,6 +18,8 @@ import { VGEO_NODE_RECORD_SIZE } from "../page/VGEO_NODE_RECORD_SIZE.js";
 import { VGEO_PAGE_HEADER_SIZE } from "../page/VGEO_PAGE_HEADER_SIZE.js";
 import { VGEO_PAGE_MAGIC } from "../frame/VGEO_PAGE_MAGIC.js";
 import { VGEO_PAGE_OFFSET } from "../page/VGEO_PAGE_OFFSET.js";
+import { VGEO_PARENT_ENTRY_SIZE } from "../page/VGEO_PARENT_ENTRY_SIZE.js";
+import { VGEO_PARENT_PAGE_ENTRY_SIZE } from "../page/VGEO_PARENT_PAGE_ENTRY_SIZE.js";
 import { vgeo_read_frame_extent } from "../frame/vgeo_read_frame_extent.js";
 import { VGeoPage } from "./VGeoPage.js";
 
@@ -127,6 +130,7 @@ export function vgeo_read_page(frame_bytes, page_index) {
     read_group_table(result);
     read_node_table(result);
     read_cluster_table(result);
+    read_parent_tables(result);
 
     return result;
 }
@@ -290,13 +294,69 @@ function read_group_table(page) {
     page.group_cluster_first = new Uint16Array(count);
     page.group_cluster_count = new Uint16Array(count);
     page.group_parent_count = new Uint16Array(count);
+    page.group_parent_first = new Uint32Array(count);
 
     for (let i = 0; i < count; i++) {
         const record = VGEO_PAGE_HEADER_SIZE + i * VGEO_GROUP_RECORD_SIZE;
 
-        page.group_cluster_first[i] = data.getUint16(record, LE);
-        page.group_cluster_count[i] = data.getUint16(record + 2, LE);
-        page.group_parent_count[i] = data.getUint16(record + 4, LE);
+        page.group_cluster_first[i] =
+            data.getUint16(record + VGEO_GROUP_OFFSET.CLUSTER_FIRST, LE);
+        page.group_cluster_count[i] =
+            data.getUint16(record + VGEO_GROUP_OFFSET.CLUSTER_COUNT, LE);
+        page.group_parent_count[i] =
+            data.getUint16(record + VGEO_GROUP_OFFSET.PARENT_CLUSTER_COUNT, LE);
+        page.group_parent_first[i] =
+            data.getUint16(record + VGEO_GROUP_OFFSET.PARENT_FIRST, LE);
+    }
+}
+
+/**
+ * The parent-page table and the group-parent table, in that order, from `parent_table_offset`.
+ *
+ * **A zero offset is a container without an upward edge**, not a malformed one: those bytes were
+ * reserved before `format_version` 4 and written as zero, so every container built earlier says
+ * so about itself, and this leaves the arrays empty rather than reading the payload as a table.
+ * Nothing downstream has to ask what version it is holding.
+ *
+ * @param {VGeoPage} page
+ * @throws {Error} when the tables run past the decoded page
+ */
+function read_parent_tables(page) {
+    const data = page.data;
+
+    const table = data.getUint32(VGEO_PAGE_OFFSET.PARENT_TABLE_OFFSET, LE);
+
+    if (table === 0) {
+        return;
+    }
+
+    const page_count = data.getUint16(VGEO_PAGE_OFFSET.PARENT_PAGE_COUNT, LE);
+    const entry_count = data.getUint16(VGEO_PAGE_OFFSET.PARENT_ENTRY_COUNT, LE);
+
+    const entries = table + page_count * VGEO_PARENT_PAGE_ENTRY_SIZE;
+    const end = entries + entry_count * VGEO_PARENT_ENTRY_SIZE;
+
+    if (end > page.bytes.byteLength) {
+        throw new Error(
+            `virtual geometry: page ${page.index} parent tables end at ${end}, past the`
+            + ` ${page.bytes.byteLength} bytes it decoded to`
+        );
+    }
+
+    page.parent_page_index = new Uint32Array(page_count);
+
+    for (let i = 0; i < page_count; i++) {
+        page.parent_page_index[i] = data.getUint32(table + i * VGEO_PARENT_PAGE_ENTRY_SIZE, LE);
+    }
+
+    page.parent_ref = new Uint16Array(entry_count);
+    page.parent_cluster = new Uint16Array(entry_count);
+
+    for (let i = 0; i < entry_count; i++) {
+        const record = entries + i * VGEO_PARENT_ENTRY_SIZE;
+
+        page.parent_ref[i] = data.getUint16(record, LE);
+        page.parent_cluster[i] = data.getUint16(record + 2, LE);
     }
 }
 

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

@@ -1 +1 @@
-{"version":3,"file":"vgeo_validate_container.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/format/vgeo_validate_container.js"],"names":[],"mappings":"AAshDA;;;;;GAKG;AACH,gDAHW,YAAY,GACV,UAAU,EAAE,CAkFxB;6BA5mD4B,4CAA4C;2BA+C9C,iBAAiB"}
+{"version":3,"file":"vgeo_validate_container.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/format/vgeo_validate_container.js"],"names":[],"mappings":"AA6tDA;;;;;GAKG;AACH,gDAHW,YAAY,GACV,UAAU,EAAE,CAqFxB;6BAtzD4B,4CAA4C;2BAmD9C,iBAAiB"}

package/src/shade/renderer/geometry/virtual/format/vgeo_validate_container.js

@@ -20,6 +20,7 @@ import { VGEO_FRAME_ALIGNMENT } from "./frame/VGEO_FRAME_ALIGNMENT.js";
 import { vgeo_frame_decode_bound } from "./frame/vgeo_frame_decode_bound.js";
 import { VGEO_FRAME_HEADER_SIZE } from "./frame/VGEO_FRAME_HEADER_SIZE.js";
 import { VGEO_FRAME_OFFSET } from "./frame/VGEO_FRAME_OFFSET.js";
+import { VGEO_GROUP_OFFSET } from "./page/VGEO_GROUP_OFFSET.js";
 import { VGEO_GROUP_RECORD_SIZE } from "./page/VGEO_GROUP_RECORD_SIZE.js";
 import { VGEO_HASH_ALGO_XXH3 } from "./header/VGEO_HASH_ALGO_XXH3.js";
 import { VGEO_HEADER_OFFSET } from "./header/VGEO_HEADER_OFFSET.js";
@@ -30,7 +31,10 @@ import { VGEO_MAX_CHILD_REF } from "./cluster/VGEO_MAX_CHILD_REF.js";
 import { VGEO_MAX_CLUSTER_TRIANGLE_COUNT } from "./cluster/VGEO_MAX_CLUSTER_TRIANGLE_COUNT.js";
 import { VGEO_MAX_CLUSTER_VERTEX_COUNT } from "./cluster/VGEO_MAX_CLUSTER_VERTEX_COUNT.js";
 import { VGEO_MAX_GROUP_CLUSTER_COUNT } from "./page/VGEO_MAX_GROUP_CLUSTER_COUNT.js";
+import { VGEO_MAX_PARENT_REF } from "./page/VGEO_MAX_PARENT_REF.js";
 import { VGEO_MIN_READER_VERSION } from "./header/VGEO_MIN_READER_VERSION.js";
+import { VGEO_PARENT_ENTRY_SIZE } from "./page/VGEO_PARENT_ENTRY_SIZE.js";
+import { VGEO_PARENT_PAGE_ENTRY_SIZE } from "./page/VGEO_PARENT_PAGE_ENTRY_SIZE.js";
 import { VGEO_NO_CHILD } from "./cluster/VGEO_NO_CHILD.js";
 import { VGEO_NO_GROUP } from "./cluster/VGEO_NO_GROUP.js";
 import { VGEO_NODE_FANOUT } from "./page/VGEO_NODE_FANOUT.js";
@@ -114,12 +118,42 @@ class DecodedPage {
     payload_offset = 0;
     payload_size = 0;
 
+    /**
+     * Start of the parent section — the parent-page table, then the group-parent table. Zero on a
+     * page written before `format_version` 4, which carries neither.
+     * @type {number}
+     */
+    parent_table_offset = 0;
+
+    /**
+     * @type {number}
+     */
+    parent_entry_count = 0;
+
+    /**
+     * @type {number}
+     */
+    parent_page_count = 0;
+
     /**
      * `[page_index, ...]` in child-table order.
      * @type {number[]}
      */
     child_pages = [];
 
+    /**
+     * `[page_index, ...]` in parent-page-table order.
+     * @type {number[]}
+     */
+    parent_pages = [];
+
+    /**
+     * The group-parent table, flat: `[parent_ref, parent_cluster, ...]` in table order, which the
+     * groups' `parent_first` slices.
+     * @type {number[]}
+     */
+    parent_entries = [];
+
     /**
      * Position `buffer` at a page-relative offset.
      * @param {number} offset
@@ -617,13 +651,9 @@ function decode_page(buffer, frame, level_count, out) {
     page.payload_size = decoded.readUint32();
     page.node_table_offset = decoded.readUint32();
 
-    for (let offset = 24; offset < VGEO_PAGE_OFFSET.METRIC; offset++) {
-        if (decoded.raw_bytes[page.base + offset] !== 0) {
-            out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${frame.page_index}: reserved byte at ${offset} in the page header is not zero`));
-
-            break;
-        }
-    }
+    page.parent_table_offset = decoded.readUint32();
+    page.parent_entry_count = decoded.readUint16();
+    page.parent_page_count = decoded.readUint16();
 
     page.seek(VGEO_PAGE_OFFSET.METRIC);
 
@@ -674,7 +704,22 @@ function decode_page(buffer, frame, level_count, out) {
         return undefined;
     }
 
-    const expected_payload_offset = page.cluster_table_offset + page.cluster_count * VGEO_CLUSTER_RECORD_SIZE;
+    const expected_parent_table_offset = page.cluster_table_offset
+        + page.cluster_count * VGEO_CLUSTER_RECORD_SIZE;
+
+    if (page.parent_table_offset !== expected_parent_table_offset) {
+        out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${frame.page_index}: parent_table_offset is ${page.parent_table_offset}, expected ${expected_parent_table_offset}`));
+
+        return undefined;
+    }
+
+    if (page.parent_page_count > page.parent_entry_count) {
+        out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${frame.page_index}: parent_page_count is ${page.parent_page_count}, above the ${page.parent_entry_count} entries that could name a page`));
+    }
+
+    const expected_payload_offset = page.parent_table_offset
+        + page.parent_page_count * VGEO_PARENT_PAGE_ENTRY_SIZE
+        + page.parent_entry_count * VGEO_PARENT_ENTRY_SIZE;
 
     if (page.payload_offset !== expected_payload_offset) {
         out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${frame.page_index}: payload_offset is ${page.payload_offset}, expected ${expected_payload_offset}`));
@@ -1016,7 +1061,7 @@ function check_child_tables(buffer, frames, pages, out) {
 /**
  * @param {DecodedPage} page
  * @param {VGeoDefect[]} out
- * @returns {{cluster_first:number, cluster_count:number, parent_cluster_count:number}[]}
+ * @returns {{cluster_first:number, cluster_count:number, parent_cluster_count:number, parent_first:number}[]}
  */
 function read_groups(page, out) {
     const result = [];
@@ -1024,19 +1069,29 @@ function read_groups(page, out) {
     const buffer = page.buffer;
 
     let expected_first = 0;
+    let expected_parent_first = 0;
 
     for (let g = 0; g < page.group_count; g++) {
-        page.seek(VGEO_PAGE_HEADER_SIZE + g * VGEO_GROUP_RECORD_SIZE);
+        const record = VGEO_PAGE_HEADER_SIZE + g * VGEO_GROUP_RECORD_SIZE;
 
-        const group = {
-            cluster_first: buffer.readUint16(),
-            cluster_count: buffer.readUint16(),
-            parent_cluster_count: buffer.readUint16(),
+        /**
+         * Each field is sought to by name rather than read in a run, so that this audit and
+         * `vgeo_read_page` address the record through the same table — a validator that agreed
+         * with the reader only by having been written in the same order is a validator that stops
+         * agreeing the first time a field moves.
+         */
+        const read = (field) => {
+            page.seek(record + field);
+
+            return buffer.readUint16();
         };
 
-        if (buffer.readUint16() !== 0) {
-            out.push(new VGeoDefect(VGEO_DEFECT.GROUP, `page ${page.page_index} group ${g}: reserved is not zero`));
-        }
+        const group = {
+            cluster_first: read(VGEO_GROUP_OFFSET.CLUSTER_FIRST),
+            cluster_count: read(VGEO_GROUP_OFFSET.CLUSTER_COUNT),
+            parent_cluster_count: read(VGEO_GROUP_OFFSET.PARENT_CLUSTER_COUNT),
+            parent_first: read(VGEO_GROUP_OFFSET.PARENT_FIRST),
+        };
 
         if (group.cluster_count < 1 || group.cluster_count > VGEO_MAX_GROUP_CLUSTER_COUNT) {
             out.push(new VGeoDefect(VGEO_DEFECT.GROUP, `page ${page.page_index} group ${g}: cluster_count ${group.cluster_count} is outside [1, ${VGEO_MAX_GROUP_CLUSTER_COUNT}]`));
@@ -1048,6 +1103,12 @@ function read_groups(page, out) {
 
         expected_first = group.cluster_first + group.cluster_count;
 
+        if (group.parent_first !== expected_parent_first) {
+            out.push(new VGeoDefect(VGEO_DEFECT.GROUP, `page ${page.page_index} group ${g}: parent_first ${group.parent_first}, expected ${expected_parent_first}; a page's groups must tile its group-parent table in order`));
+        }
+
+        expected_parent_first = group.parent_first + group.parent_cluster_count;
+
         result.push(group);
     }
 
@@ -1055,9 +1116,147 @@ function read_groups(page, out) {
         out.push(new VGeoDefect(VGEO_DEFECT.GROUP, `page ${page.page_index}: groups cover ${expected_first} clusters, the page holds ${page.cluster_count}`));
     }
 
+    if (expected_parent_first !== page.parent_entry_count) {
+        out.push(new VGeoDefect(VGEO_DEFECT.GROUP, `page ${page.page_index}: groups cover ${expected_parent_first} parent entries, the page's table holds ${page.parent_entry_count}`));
+    }
+
     return result;
 }
 
+/**
+ * Read the two parent tables onto the page, and check the shape of what they hold before anything
+ * tries to resolve it.
+ *
+ * @param {DecodedPage} page
+ * @param {VGeoDefect[]} out
+ */
+function read_parent_tables(page, out) {
+    const buffer = page.buffer;
+
+    page.seek(page.parent_table_offset);
+
+    for (let i = 0; i < page.parent_page_count; i++) {
+        page.parent_pages.push(buffer.readUint32());
+    }
+
+    // Ascending and distinct, so that a parent page resolves to one reference and the refine-side
+    // election in a runtime reading this table is deterministic.
+    for (let i = 1; i < page.parent_pages.length; i++) {
+        if (page.parent_pages[i] <= page.parent_pages[i - 1]) {
+            out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${page.page_index} parent page entry ${i}: page index ${page.parent_pages[i]} does not follow ${page.parent_pages[i - 1]}; the table is ascending and deduplicated`));
+
+            break;
+        }
+    }
+
+    for (const parent_page of page.parent_pages) {
+        if (parent_page === page.page_index) {
+            out.push(new VGeoDefect(VGEO_DEFECT.PAGE_LAYOUT, `page ${page.page_index}: its own index is in its parent-page table, where SAME_PAGE belongs`));
+
+            break;
+        }
+    }
+
+    page.seek(page.parent_table_offset + page.parent_page_count * VGEO_PARENT_PAGE_ENTRY_SIZE);
+
+    for (let i = 0; i < page.parent_entry_count; i++) {
+        const parent_ref = buffer.readUint16();
+        const parent_cluster = buffer.readUint16();
+
+        if (parent_ref !== VGEO_SAME_PAGE
+            && (parent_ref > VGEO_MAX_PARENT_REF || parent_ref >= page.parent_page_count)) {
+            out.push(new VGeoDefect(VGEO_DEFECT.GROUP, `page ${page.page_index} parent entry ${i}: parent_ref ${parent_ref} is outside the ${page.parent_page_count}-entry parent-page table`));
+        }
+
+        page.parent_entries.push(parent_ref, parent_cluster);
+    }
+}
+
+/**
+ * The upward edge, checked against the downward one it mirrors — format §11.16.
+ *
+ * Every parent reference must resolve to a cluster that really does name this group as its child,
+ * and each group's list must be sorted and free of repeats. The first is what makes a coarsen legal
+ * at all; the second is what lets a runtime elect one appender out of a group's parents by taking
+ * the first entry of the list, rather than carrying a bitmask sized by instances times groups.
+ *
+ * It is checked by rebuilding the lists from the cluster records and comparing, rather than by
+ * resolving each reference on its own: the downward edge is already validated by {@link check_dag},
+ * so rebuilding from it catches a *missing* parent as well as a wrong one.
+ *
+ * @param {DecodedPage[]} pages
+ * @param {object[][]} page_groups
+ * @param {object[][]} page_clusters
+ * @param {VGeoDefect[]} out
+ */
+function check_parent_tables(pages, page_groups, page_clusters, out) {
+    /**
+     * `page:group` to the parents the cluster records say it has, in the order §11.16 requires.
+     * @type {Map<string, {page: number, cluster: number}[]>}
+     */
+    const expected = new Map();
+
+    for (const page of pages) {
+        for (const cluster of page_clusters[page.page_index]) {
+            if (cluster.child_ref === VGEO_NO_CHILD) {
+                continue;
+            }
+
+            const child_page = cluster.child_ref === VGEO_SAME_PAGE
+                ? page.page_index
+                : page.child_pages[cluster.child_ref];
+
+            if (child_page === undefined) {
+                // a broken child reference, which check_dag reports; nothing to mirror
+                continue;
+            }
+
+            const id = `${child_page}:${cluster.child_group}`;
+
+            let list = expected.get(id);
+
+            if (list === undefined) {
+                expected.set(id, list = []);
+            }
+
+            list.push({ page: page.page_index, cluster: cluster.index });
+        }
+    }
+
+    for (const list of expected.values()) {
+        list.sort((a, b) => a.page - b.page || a.cluster - b.cluster);
+    }
+
+    for (const page of pages) {
+        page_groups[page.page_index].forEach((group, group_index) => {
+            const want = expected.get(`${page.page_index}:${group_index}`) ?? [];
+
+            if (group.parent_first + group.parent_cluster_count > page.parent_entry_count) {
+                out.push(new VGeoDefect(VGEO_DEFECT.GROUP, `page ${page.page_index} group ${group_index}: parents ${group.parent_first}..${group.parent_first + group.parent_cluster_count} run past the ${page.parent_entry_count}-entry table`));
+
+                return;
+            }
+
+            for (let i = 0; i < group.parent_cluster_count && i < want.length; i++) {
+                const base = (group.parent_first + i) * 2;
+
+                const parent_ref = page.parent_entries[base];
+                const parent_cluster = page.parent_entries[base + 1];
+
+                const named_page = parent_ref === VGEO_SAME_PAGE
+                    ? page.page_index
+                    : page.parent_pages[parent_ref];
+
+                if (named_page !== want[i].page || parent_cluster !== want[i].cluster) {
+                    out.push(new VGeoDefect(VGEO_DEFECT.GROUP, `page ${page.page_index} group ${group_index} parent ${i}: names page ${named_page} cluster ${parent_cluster}, but the ${i}th cluster refining into this group is page ${want[i].page} cluster ${want[i].cluster}`));
+
+                    break;
+                }
+            }
+        });
+    }
+}
+
 /**
  * Decode a cluster's local positions from its payload — the only way to check that the culling
  * bounds actually bound anything.
@@ -1617,6 +1816,8 @@ export function vgeo_validate_container(buffer) {
         const groups = read_groups(page, out);
         const clusters = read_clusters(page, out);
 
+        read_parent_tables(page, out);
+
         page_groups.push(groups);
         page_clusters.push(clusters);
 
@@ -1637,6 +1838,7 @@ export function vgeo_validate_container(buffer) {
     }
 
     check_page_nodes(pages, page_groups, page_clusters, out);
+    check_parent_tables(pages, page_groups, page_clusters, out);
 
     check_dag(pages, page_groups, page_clusters, level_count, out);
     check_directory(buffer, frames, pages, out);

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

@@ -1 +1 @@
-{"version":3,"file":"vgeo_write_container.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/format/vgeo_write_container.js"],"names":[],"mappings":"AAmTA;;;;;;;;GAQG;AACH,4CANW,qBAAqB,8BAGnB,YAAY,CAmNxB;6BA3gB4B,4CAA4C"}
+{"version":3,"file":"vgeo_write_container.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/geometry/virtual/format/vgeo_write_container.js"],"names":[],"mappings":"AAocA;;;;;;;;GAQG;AACH,4CANW,qBAAqB,8BAGnB,YAAY,CAmNxB;6BA5pB4B,4CAA4C"}