@woosh/meep-engine 3.26.0 → 3.28.0

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

@@ -17,6 +17,7 @@ import { VGEO_FORMAT_VERSION } from "./header/VGEO_FORMAT_VERSION.js";
 import { VGEO_FRAME_ALIGNMENT } from "./frame/VGEO_FRAME_ALIGNMENT.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";
@@ -24,6 +25,8 @@ import { VGEO_HEADER_SIZE } from "./header/VGEO_HEADER_SIZE.js";
 import { VGEO_LEVEL_RECORD_SIZE } from "./header/VGEO_LEVEL_RECORD_SIZE.js";
 import { VGEO_MAGIC } from "./header/VGEO_MAGIC.js";
 import { VGEO_MAX_CHILD_REF } from "./cluster/VGEO_MAX_CHILD_REF.js";
+import { VGEO_MAX_PARENT_ENTRY_COUNT } from "./page/VGEO_MAX_PARENT_ENTRY_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_NO_CHILD } from "./cluster/VGEO_NO_CHILD.js";
 import { VGEO_NO_GROUP } from "./cluster/VGEO_NO_GROUP.js";
@@ -32,7 +35,10 @@ 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_PAYLOAD_ENCODING_SHADE_MESHLET_V1 } from "./header/VGEO_PAYLOAD_ENCODING_SHADE_MESHLET_V1.js";
+import { VGEO_SAME_PAGE } from "./cluster/VGEO_SAME_PAGE.js";
 import { vgeo_scan_frames } from "./frame/vgeo_scan_frames.js";
 
 /**
@@ -98,28 +104,84 @@ class PageBlob {
 }
 
 /**
- * Count how many clusters name each group, and index the groups within their pages. Both are
- * derived, so recomputing them here keeps a caller from having to maintain them.
+ * Count how many clusters name each group, index the groups and clusters within their pages, and
+ * build the upward edge. All of it is derived, so recomputing it here keeps a caller from having to
+ * maintain any of it.
+ *
+ * The upward edge is the one piece that cannot be resolved while a single page is written: a
+ * group's parents live in whichever pages happen to refine into it, so the map is built across the
+ * whole page set once and then read per page.
  *
  * @param {VirtualGeometryPage[]} pages
+ * @returns {Map<VirtualGeometryGroup, {page: number, cluster: number}[]>} each group's parents,
+ *     sorted by (page index, cluster index) — the order format §11.16 requires, and the order the
+ *     runtime's refine-side election depends on being deterministic
  */
 function resolve_group_references(pages) {
     for (const page of pages) {
+        let cluster_index = 0;
+
         page.groups.forEach((group, index) => {
             group.index_in_page = index;
             group.parent_cluster_count = 0;
+
+            for (const cluster of group.clusters) {
+                cluster.index_in_page = cluster_index;
+                cluster_index++;
+            }
         });
     }
 
+    /** @type {Map<VirtualGeometryGroup, {page: number, cluster: number}[]>} */
+    const parents = new Map();
+
     for (const page of pages) {
         for (const group of page.groups) {
             for (const cluster of group.clusters) {
-                if (cluster.child_group !== undefined) {
-                    cluster.child_group.parent_cluster_count++;
+                const child = cluster.child_group;
+
+                if (child === undefined) {
+                    continue;
+                }
+
+                child.parent_cluster_count++;
+
+                let list = parents.get(child);
+
+                if (list === undefined) {
+                    parents.set(child, list = []);
                 }
+
+                list.push({ page: page.index, cluster: cluster.index_in_page });
             }
         }
     }
+
+    for (const list of parents.values()) {
+        list.sort((a, b) => a.page - b.page || a.cluster - b.cluster);
+    }
+
+    return parents;
+}
+
+/**
+ * @param {VirtualGeometryPage} page
+ * @param {Map<VirtualGeometryGroup, {page: number, cluster: number}[]>} parents
+ * @returns {number[]} distinct indices of *other* pages holding a parent of one of this page's
+ *     groups, ascending; a parent in this page is named by `VGEO_SAME_PAGE` and is not here
+ */
+function collect_parent_pages(page, parents) {
+    const seen = new Set();
+
+    for (const group of page.groups) {
+        for (const parent of parents.get(group) ?? []) {
+            if (parent.page !== page.index) {
+                seen.add(parent.page);
+            }
+        }
+    }
+
+    return Array.from(seen).sort((a, b) => a - b);
 }
 
 /**
@@ -149,9 +211,10 @@ function collect_child_pages(page) {
 /**
  * @param {VirtualGeometryPage} page
  * @param {number[]} child_pages
+ * @param {Map<VirtualGeometryGroup, {page: number, cluster: number}[]>} parents
  * @returns {Uint8Array} the decoded page
  */
-function build_page_blob(page, child_pages) {
+function build_page_blob(page, child_pages, parents) {
     const clusters = [];
 
     for (const group of page.groups) {
@@ -160,9 +223,41 @@ function build_page_blob(page, child_pages) {
         }
     }
 
+    const parent_pages = collect_parent_pages(page, parents);
+
+    let parent_entry_count = 0;
+
+    for (const group of page.groups) {
+        parent_entry_count += (parents.get(group) ?? []).length;
+    }
+
+    assert.lessThanOrEqual(
+        parent_entry_count, VGEO_MAX_PARENT_ENTRY_COUNT,
+        'page group-parent table must stay within what parent_first can index (format §11.15)'
+    );
+
+    assert.lessThanOrEqual(
+        parent_pages.length, VGEO_MAX_PARENT_REF + 1,
+        'page parent-page table must stay within what parent_ref can index'
+    );
+
     const node_table_offset = VGEO_PAGE_HEADER_SIZE + page.groups.length * VGEO_GROUP_RECORD_SIZE;
     const cluster_table_offset = node_table_offset + page.nodes.length * VGEO_NODE_RECORD_SIZE;
-    const payload_offset = cluster_table_offset + clusters.length * VGEO_CLUSTER_RECORD_SIZE;
+
+    /*
+     The parent section sits between the cluster records and the payload rather than beside the
+     group table, which keeps `node_table_offset`'s "= 56 + 8·group_count" true and leaves every
+     offset a reader before format 4 computed exactly where it was. Both tables hold 4-byte entries
+     and the sections above them are all multiples of four, so the payload stays word-aligned —
+     format §11.8's promise, which the meshlet batch divides by four without rounding.
+    */
+    const parent_table_offset = cluster_table_offset + clusters.length * VGEO_CLUSTER_RECORD_SIZE;
+
+    const group_parent_table_offset = parent_table_offset
+        + parent_pages.length * VGEO_PARENT_PAGE_ENTRY_SIZE;
+
+    const payload_offset = group_parent_table_offset
+        + parent_entry_count * VGEO_PARENT_ENTRY_SIZE;
 
     let payload_size = 0;
 
@@ -185,6 +280,9 @@ function build_page_blob(page, child_pages) {
     buffer.writeUint32(payload_offset);
     buffer.writeUint32(payload_size);
     buffer.writeUint32(node_table_offset);
+    buffer.writeUint32(parent_table_offset);
+    buffer.writeUint16(parent_entry_count);
+    buffer.writeUint16(parent_pages.length);
 
     // The page's own metric, so an installed page can be re-tested from itself rather than from
     // whichever of its parents happened to reference it.
@@ -216,16 +314,63 @@ function build_page_blob(page, child_pages) {
         child_ref_of_page.set(page_index, index);
     });
 
+    /**
+     * `page_index -> parent-page-table index`. The same shape as above and resolved the same way;
+     * a parent inside this page is `VGEO_SAME_PAGE` and is not in the table at all.
+     * @type {Map<number, number>}
+     */
+    const parent_ref_of_page = new Map();
+
+    parent_pages.forEach((page_index, index) => {
+        assert.lessThanOrEqual(index, VGEO_MAX_PARENT_REF, 'parent table index must stay below the sentinel range');
+
+        parent_ref_of_page.set(page_index, index);
+    });
+
+    parent_pages.forEach((page_index, index) => {
+        buffer.position = parent_table_offset + index * VGEO_PARENT_PAGE_ENTRY_SIZE;
+
+        buffer.writeUint32(page_index);
+    });
+
     let cluster_index = 0;
     let cursor = 0;
 
+    let parent_first = 0;
+
     page.groups.forEach((group, group_index) => {
-        buffer.position = VGEO_PAGE_HEADER_SIZE + group_index * VGEO_GROUP_RECORD_SIZE;
+        const group_parents = parents.get(group) ?? [];
 
+        assert.equal(
+            group_parents.length, group.parent_cluster_count,
+            'a group\'s parent list and its parent_cluster_count are the same fact twice'
+        );
+
+        group_parents.forEach((parent, index) => {
+            buffer.position = group_parent_table_offset
+                + (parent_first + index) * VGEO_PARENT_ENTRY_SIZE;
+
+            buffer.writeUint16(
+                parent.page === page.index ? VGEO_SAME_PAGE : parent_ref_of_page.get(parent.page)
+            );
+            buffer.writeUint16(parent.cluster);
+        });
+
+        const group_record = VGEO_PAGE_HEADER_SIZE + group_index * VGEO_GROUP_RECORD_SIZE;
+
+        buffer.position = group_record + VGEO_GROUP_OFFSET.CLUSTER_FIRST;
         buffer.writeUint16(cluster_index);
+
+        buffer.position = group_record + VGEO_GROUP_OFFSET.CLUSTER_COUNT;
         buffer.writeUint16(group.clusters.length);
+
+        buffer.position = group_record + VGEO_GROUP_OFFSET.PARENT_CLUSTER_COUNT;
         buffer.writeUint16(group.parent_cluster_count);
-        buffer.writeUint16(0);
+
+        buffer.position = group_record + VGEO_GROUP_OFFSET.PARENT_FIRST;
+        buffer.writeUint16(parent_first);
+
+        parent_first += group_parents.length;
 
         for (const cluster of group.clusters) {
             const offset = cluster_table_offset + cluster_index * VGEO_CLUSTER_RECORD_SIZE;
@@ -322,19 +467,19 @@ export function vgeo_write_container(pages, options) {
         assert.equal(page.index, index, `page ${index} carries index ${page.index}`);
     });
 
-    resolve_group_references(pages);
+    const parents = resolve_group_references(pages);
 
     const blobs = pages.map((page) => {
         const blob = new PageBlob();
 
         blob.child_pages = collect_child_pages(page);
 
-        const decoded = build_page_blob(page, blob.child_pages);
+        const decoded = build_page_blob(page, blob.child_pages, parents);
 
         // Compression happens here, before a single offset is known, and that is what keeps the
         // layout non-circular: a frame's extent follows from its *stored* size and its child count,
         // and neither depends on any offset value, because the child table is plaintext.
-        const encoded = vgeo_encode_frame_blob(decoded, options.codec);
+        const encoded = vgeo_encode_frame_blob(decoded, options.codec, options.codec_level);
 
         blob.codec = encoded.codec;
         blob.stored = encoded.bytes;