@woosh/meep-engine 3.27.0 → 3.29.0

package/src/shade/renderer/shader/chunk/geometry/mat4/chunk_mat4_linear_determinant.js

@@ -0,0 +1,18 @@
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+
+/**
+ * Determinant of the linear (upper-left 3x3) part of a 4x4 transform. WGSL twin of
+ * {@link m4_linear_determinant} — keep the two in step.
+ *
+ * Negative exactly when the transform reflects, which is what reverses triangle winding and
+ * tangent-frame handedness under it.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_mat4_linear_determinant = CodeChunk.from(
+    //language=WGSL
+    `
+fn mat4_linear_determinant( m: mat4x4<f32> ) -> f32{
+    return dot( m[0].xyz, cross( m[1].xyz, m[2].xyz ) );
+}
+`, [])

package/src/shade/renderer/shader/chunk/geometry/triangle/chunk_triangle_list_reverse_winding.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Programmable winding for a non-indexed `triangle-list` draw.
+ *
+ * Maps a `@builtin(vertex_index)` to the one that puts the same three vertices on the rasterizer
+ * in the opposite order: corners `0,1,2` of a triangle become `2,1,0`. That is an odd permutation,
+ * so the emitted winding reverses, and it is the only thing needed to make a reflected instance
+ * face the right way — front-face determination is fixed-function and reads screen-space winding
+ * alone, and WebGPU has no per-draw `frontFace` state to reach it with.
+ *
+ * Only the order changes: the same three vertices are emitted, so coverage (the fill rule is
+ * defined on the triangle's interior, not its vertex order), depth, and barycentric interpolation
+ * are all untouched. `flat` varyings are safe as long as they are constant across the triangle,
+ * which for a visibility buffer's mesh/triangle ids they are.
+ *
+ * Safe to apply to the raw builtin, before any clamp or bounds guard: a meshlet's padding vertices
+ * begin at `primitive_count * 3`, always a corner-0 boundary, so the permutation maps each padding
+ * triple onto itself and can never move a padding vertex into range or a real one out of it.
+ *
+ * @see chunk_node3d_flags for where the `reverse` bit comes from
+ * @type {CodeChunk}
+ */
+export const chunk_triangle_list_reverse_winding: CodeChunk;
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_triangle_list_reverse_winding.d.ts.map

package/src/shade/renderer/shader/chunk/geometry/triangle/chunk_triangle_list_reverse_winding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_triangle_list_reverse_winding.d.ts","sourceRoot":"","sources":["../../../../../../../../src/shade/renderer/shader/chunk/geometry/triangle/chunk_triangle_list_reverse_winding.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,kDAFU,SAAS,CAWb;0BAhCoB,gCAAgC"}

package/src/shade/renderer/shader/chunk/geometry/triangle/chunk_triangle_list_reverse_winding.js

@@ -0,0 +1,33 @@
+import { CodeChunk } from "../../../compiler/CodeChunk.js";
+
+/**
+ * Programmable winding for a non-indexed `triangle-list` draw.
+ *
+ * Maps a `@builtin(vertex_index)` to the one that puts the same three vertices on the rasterizer
+ * in the opposite order: corners `0,1,2` of a triangle become `2,1,0`. That is an odd permutation,
+ * so the emitted winding reverses, and it is the only thing needed to make a reflected instance
+ * face the right way — front-face determination is fixed-function and reads screen-space winding
+ * alone, and WebGPU has no per-draw `frontFace` state to reach it with.
+ *
+ * Only the order changes: the same three vertices are emitted, so coverage (the fill rule is
+ * defined on the triangle's interior, not its vertex order), depth, and barycentric interpolation
+ * are all untouched. `flat` varyings are safe as long as they are constant across the triangle,
+ * which for a visibility buffer's mesh/triangle ids they are.
+ *
+ * Safe to apply to the raw builtin, before any clamp or bounds guard: a meshlet's padding vertices
+ * begin at `primitive_count * 3`, always a corner-0 boundary, so the permutation maps each padding
+ * triple onto itself and can never move a padding vertex into range or a real one out of it.
+ *
+ * @see chunk_node3d_flags for where the `reverse` bit comes from
+ * @type {CodeChunk}
+ */
+export const chunk_triangle_list_reverse_winding = CodeChunk.from(
+    //language=WGSL
+    `
+fn triangle_list_reverse_winding( draw_index: u32, reverse: bool ) -> u32{
+    // corner 0 -> +2, corner 1 -> +0, corner 2 -> -2
+    let reversed = draw_index + 2u - ( draw_index % 3u ) * 2u;
+
+    return select( draw_index, reversed, reverse );
+}
+`, [])

package/src/shade/renderer/shadow/map/DEFAULT_SHADOWMAP_UPDATE_BUDGET.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Default per-frame shadow refresh budget, measured in **views** (one cube face counts as one
+ * view, one CSM cascade counts as one view, etc.). A point light costs 6 views, a spot light 1, a
+ * directional SHADOWMAP_CSM_CASCADE_COUNT. A bigger light consumes more of the budget, which
+ * keeps the cost of the refresh step roughly proportional to how much work we're asking the
+ * GPU to do — a single point light running the meshlet rasterization pipeline 6 times is
+ * equivalent work to 6 spot lights.
+ *
+ * Directional lights are always refreshed unconditionally (they drive the whole scene) and
+ * their view cost is charged against the budget, so they effectively reduce the pool available
+ * for local lights that frame.
+ *
+ * Unused budget is carried over between frames when demand exceeds supply. This lets a light
+ * that's too expensive to fit in a single frame (e.g. a point needing 6 views when only 2 are
+ * free) eventually get its turn without permanently starving other lights.
+ *
+ * Only the starting value: what a scene actually spends is
+ * {@link GPUSceneShadowmapContext.update_budget}, which the renderer pushes from
+ * {@link Renderer.shadow_update_budget} every frame. Raise it to keep more lights current for more
+ * raster work per frame, lower it to spend less.
+ *
+ * @type {number}
+ */
+export const DEFAULT_SHADOWMAP_UPDATE_BUDGET: number;
+//# sourceMappingURL=DEFAULT_SHADOWMAP_UPDATE_BUDGET.d.ts.map

package/src/shade/renderer/shadow/map/DEFAULT_SHADOWMAP_UPDATE_BUDGET.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DEFAULT_SHADOWMAP_UPDATE_BUDGET.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/map/DEFAULT_SHADOWMAP_UPDATE_BUDGET.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,8CAFU,MAAM,CAEiC"}

package/src/shade/renderer/shadow/map/DEFAULT_SHADOWMAP_UPDATE_BUDGET.js

@@ -0,0 +1,24 @@
+/**
+ * Default per-frame shadow refresh budget, measured in **views** (one cube face counts as one
+ * view, one CSM cascade counts as one view, etc.). A point light costs 6 views, a spot light 1, a
+ * directional SHADOWMAP_CSM_CASCADE_COUNT. A bigger light consumes more of the budget, which
+ * keeps the cost of the refresh step roughly proportional to how much work we're asking the
+ * GPU to do — a single point light running the meshlet rasterization pipeline 6 times is
+ * equivalent work to 6 spot lights.
+ *
+ * Directional lights are always refreshed unconditionally (they drive the whole scene) and
+ * their view cost is charged against the budget, so they effectively reduce the pool available
+ * for local lights that frame.
+ *
+ * Unused budget is carried over between frames when demand exceeds supply. This lets a light
+ * that's too expensive to fit in a single frame (e.g. a point needing 6 views when only 2 are
+ * free) eventually get its turn without permanently starving other lights.
+ *
+ * Only the starting value: what a scene actually spends is
+ * {@link GPUSceneShadowmapContext.update_budget}, which the renderer pushes from
+ * {@link Renderer.shadow_update_budget} every frame. Raise it to keep more lights current for more
+ * raster work per frame, lower it to spend less.
+ *
+ * @type {number}
+ */
+export const DEFAULT_SHADOWMAP_UPDATE_BUDGET = 8;

package/src/shade/renderer/shadow/map/GPUSceneShadowmapContext.d.ts

@@ -50,6 +50,16 @@ export class GPUSceneShadowmapContext {
      * @type {boolean}
      */
     use_tetrahedron_point_shadows: boolean;
+    /**
+     * @param {number} v views per frame, at least one. A higher budget keeps more lights current
+     *        and rasterizes more per frame; a lower one refreshes fewer of them per frame and
+     *        leaves the rest sampling older depth until their turn comes around.
+     */
+    set update_budget(v: number);
+    /**
+     * @returns {number} views this scene may spend refreshing shadowmaps each frame
+     */
+    get update_budget(): number;
     /**
      * @returns {number} number of shadowmaps rasterized in the most recent draw pass
      */

package/src/shade/renderer/shadow/map/GPUSceneShadowmapContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUSceneShadowmapContext.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/map/GPUSceneShadowmapContext.js"],"names":[],"mappings":"AAyGA;;GAEG;AACH;IAoNI;;;;;;;;OAQG;IACH,sBAPW,eAAe,aACf,eAAe,SAGf,kBAAkB,EA+D5B;IAxRD,2BAAwG;IAExG;;;OAGG;IACH,SAFU,iBAAiB,CAEnB;IAQR;;;;;;;;OAQG;IACH,qBAFU,WAAW,CAED;IAsCpB;;;;;;;;OAQG;IACH,SAFU,OAAO,CAEF;IAEf;;;;;;;;;;OAUG;IACH,+BAFU,OAAO,CAEqB;IA2EtC;;OAEG;IACH,iCAEC;IAED;;;;;;OAMG;IACH,oCAEC;IAED;;;;;OAKG;IACH,oCAEC;IAkGD;;;;;OAKG;IACH,iCAMC;IAgHD;;;;OAIG;IACH,eAHW,KAAK,GACH,SAAS,GAAC,SAAS,CAI/B;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACH,6BAPW,MAAM,SAEN,eAAe,eACf,MAAM,mBACN,UAAU,MAAM,CAAC,QAgE3B;IAyED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,kBAFW,sBAAsB,QAsFhC;IAsbD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,kBALa,OAAO,CAwOnB;IAED;;;;OAIG;IACH,iBAHW,MAAM,GACJ,KAAK,CAWjB;IAED,gBAiBC;;CACJ;qCA38CY,OAAO,2CAA2C,EAAE,sBAAsB;8BAC1E,OAAO,0BAA0B,EAAE,eAAe;qBAClD,OAAO,wBAAwB,EAAE,MAAM;iCACvC,OAAO,mCAAmC,EAAE,kBAAkB;oBAC9D,OAAO,4BAA4B,EAAE,KAAK;8BAC1C,OAAO,gCAAgC,EAAE,eAAe;wBACxD,OAAO,gBAAgB,EAAE,SAAS;oCA7DX,+DAA+D;kCAkBjE,oCAAoC;4BAG1C,2BAA2B;kBAtBrC,wCAAwC"}
+{"version":3,"file":"GPUSceneShadowmapContext.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/shadow/map/GPUSceneShadowmapContext.js"],"names":[],"mappings":"AAsFA;;GAEG;AACH;IAgPI;;;;;;;;OAQG;IACH,sBAPW,eAAe,aACf,eAAe,SAGf,kBAAkB,EA+D5B;IApTD,2BAAwG;IAExG;;;OAGG;IACH,SAFU,iBAAiB,CAEnB;IAQR;;;;;;;;OAQG;IACH,qBAFU,WAAW,CAED;IAsCpB;;;;;;;;OAQG;IACH,SAFU,OAAO,CAEF;IAEf;;;;;;;;;;OAUG;IACH,+BAFU,OAAO,CAEqB;IA2BtC;;;;OAIG;IACH,6BAIC;IAhBD;;OAEG;IACH,4BAEC;IA8ED;;OAEG;IACH,iCAEC;IAED;;;;;;OAMG;IACH,oCAEC;IAED;;;;;OAKG;IACH,oCAEC;IAkGD;;;;;OAKG;IACH,iCAMC;IAgHD;;;;OAIG;IACH,eAHW,KAAK,GACH,SAAS,GAAC,SAAS,CAI/B;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2CG;IACH,6BAPW,MAAM,SAEN,eAAe,eACf,MAAM,mBACN,UAAU,MAAM,CAAC,QAgE3B;IAyED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,kBAFW,sBAAsB,QAsFhC;IAsbD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,kBALa,OAAO,CAwOnB;IAED;;;;OAIG;IACH,iBAHW,MAAM,GACJ,KAAK,CAWjB;IAED,gBAiBC;;CACJ;qCAn9CY,OAAO,2CAA2C,EAAE,sBAAsB;8BAC1E,OAAO,0BAA0B,EAAE,eAAe;qBAClD,OAAO,wBAAwB,EAAE,MAAM;iCACvC,OAAO,mCAAmC,EAAE,kBAAkB;oBAC9D,OAAO,4BAA4B,EAAE,KAAK;8BAC1C,OAAO,gCAAgC,EAAE,eAAe;wBACxD,OAAO,gBAAgB,EAAE,SAAS;oCA9DX,+DAA+D;kCAkBjE,oCAAoC;4BAG1C,2BAA2B;kBAtBrC,wCAAwC"}

package/src/shade/renderer/shadow/map/GPUSceneShadowmapContext.js

@@ -30,6 +30,7 @@ import {
     shader_csm_caster_range_accumulate,
     shader_csm_caster_range_publish,
 } from "./csm/shader/shader_csm_caster_range.js";
+import { DEFAULT_SHADOWMAP_UPDATE_BUDGET } from "./DEFAULT_SHADOWMAP_UPDATE_BUDGET.js";
 import { DirectionalLightShadowmap } from "./DirectionalLightShadowmap.js";
 import { POINT_SHADOW_CUBE_COLS, POINT_SHADOW_CUBE_ROWS } from "./POINT_SHADOW_CUBE_LAYOUT.js";
 import {
@@ -83,26 +84,6 @@ const DEFAULT_SHADOWMAP_DIRECTIONAL_RESOLUTION = [
  */
 const DEFAULT_SHADOWMAP_LOCAL_RESOLUTION = 128;
 
-/**
- * Per-frame shadow refresh budget, measured in **views** (one cube face counts as one view,
- * one CSM cascade counts as one view, etc.). A point light costs 6 views, a spot light 1, a
- * directional SHADOWMAP_CSM_CASCADE_COUNT. A bigger light consumes more of the budget, which
- * keeps the cost of the refresh step roughly proportional to how much work we're asking the
- * GPU to do — a single point light running the meshlet rasterization pipeline 6 times is
- * equivalent work to 6 spot lights.
- *
- * Directional lights are always refreshed unconditionally (they drive the whole scene) and
- * their view cost is charged against the budget, so they effectively reduce the pool available
- * for local lights that frame.
- *
- * Unused budget is carried over between frames when demand exceeds supply — see
- * {@link GPUSceneShadowmapContext.#budget_carry_over}. This lets a light that's too expensive
- * to fit in a single frame (e.g. a point needing 6 views when only 2 are free) eventually get
- * its turn without permanently starving other lights.
- * @type {number}
- */
-const SHADOWMAP_UPDATE_BUDGET = 8;
-
 /**
  * Shadows for a single scene
  */
@@ -200,6 +181,34 @@ export class GPUSceneShadowmapContext {
      */
     #current_frame_index = -1;
 
+    /**
+     * Per-frame refresh budget in views, spent by {@link select_for_draw} on top of
+     * {@link #budget_carry_over}. Defaults to {@link DEFAULT_SHADOWMAP_UPDATE_BUDGET}, which is
+     * also where the view accounting is written down; the renderer pushes its own
+     * {@link Renderer.shadow_update_budget} here before each frame's light update, alongside
+     * {@link enabled}.
+     * @type {number}
+     */
+    #update_budget = DEFAULT_SHADOWMAP_UPDATE_BUDGET;
+
+    /**
+     * @returns {number} views this scene may spend refreshing shadowmaps each frame
+     */
+    get update_budget() {
+        return this.#update_budget;
+    }
+
+    /**
+     * @param {number} v views per frame, at least one. A higher budget keeps more lights current
+     *        and rasterizes more per frame; a lower one refreshes fewer of them per frame and
+     *        leaves the rest sampling older depth until their turn comes around.
+     */
+    set update_budget(v) {
+        assert.isPositiveInteger(v, 'update_budget');
+
+        this.#update_budget = v;
+    }
+
     /**
      * View-budget surplus carried forward from prior frames. Accumulates whenever we had
      * non-directional candidates that couldn't fit in the per-frame budget (i.e. a point light
@@ -602,7 +611,7 @@ export class GPUSceneShadowmapContext {
         // Steps 4 and 5: score every map and greedy-fill the view budget in score order. See
         // ShadowmapDrawSelector for why this is a heap drain rather than a sort — the budget
         // consumes a handful of winners out of however many candidates the scene has.
-        const budget_total = SHADOWMAP_UPDATE_BUDGET + this.#budget_carry_over;
+        const budget_total = this.#update_budget + this.#budget_carry_over;
         const selector = this.#selector;
 
         selector.select(shadowmaps, frame_index, budget_total);

package/src/core/model/node-graph/visual/layout/LayoutBoxGraph.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"LayoutBoxGraph.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/model/node-graph/visual/layout/LayoutBoxGraph.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH,8BAFU,MAAM,CAEiB;AAEjC;;;;;;;;GAQG;AACH,8BAFU,MAAM,CAEiB;AAEjC;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAyFI;;;OAGG;IACH,wBAHW,MAAM,eACN,MAAM,EAIhB;IA7FD;;OAEG;IACH,WAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,OAFU,YAAY,CAEhB;IAEN;;;OAGG;IACH,OAFU,YAAY,CAEhB;IAEN;;OAEG;IACH,OAFU,YAAY,CAEhB;IAEN;;OAEG;IACH,OAFU,YAAY,CAEhB;IAEN;;;OAGG;IACH,WAFU,UAAU,CAEV;IAEV;;;OAGG;IACH,UAFU,UAAU,CAEX;IAET;;OAEG;IACH,YAFU,MAAM,CAED;IAEf;;OAEG;IACH,WAFU,UAAU,CAEV;IAEV;;OAEG;IACH,SAFU,UAAU,CAEZ;IAER;;;OAGG;IACH,aAFU,YAAY,CAEV;IAEZ;;;OAGG;IACH,WAFU,YAAY,CAEZ;IAEV;;;OAGG;IACH,YAFU,UAAU,CAET;IAEX;;OAEG;IACH,UAFU,UAAU,CAEX;IAET;;OAEG;IACH,WAFU,UAAU,CAEV;IAEV;;OAEG;IACH,SAFU,UAAU,CAEZ;IAUR;;;;;;;;;OASG;IACH,kBAJW,MAAM,cACN,MAAM,GACJ,IAAI,CAwBhB;IAED;;;;;;OAMG;IACH,eANW,MAAM,SACN,MAAM,UACN,MAAM,QACN,MAAM,GACJ,IAAI,CAMhB;IAED;;;;;;;OAOG;IACH,gBAPW,MAAM,QACN,MAAM,MACN,MAAM,UACN,MAAM,QACN,MAAM,GACJ,IAAI,CAOhB;IAED;;;;;;;;OAQG;IACH,mBAFa,IAAI,CAsChB;IAED;;;OAGG;IACH,gBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,eAHW,MAAM,GACJ,MAAM,CAIlB;CACJ"}

package/src/core/model/node-graph/visual/layout/layout_assign_coordinates.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"layout_assign_coordinates.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/model/node-graph/visual/layout/layout_assign_coordinates.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,8EAVW,MAAM,SACN,UAAU,QACV,UAAU,eACV,UAAU,oCAER;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CAgC3C"}

package/src/core/model/node-graph/visual/layout/layout_assign_layers.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"layout_assign_layers.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/model/node-graph/visual/layout/layout_assign_layers.js"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,sEAPW,UAAU,GAER,MAAM,CAsDlB"}

package/src/core/model/node-graph/visual/layout/layout_break_cycles.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"layout_break_cycles.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/model/node-graph/visual/layout/layout_break_cycles.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,4DANa,UAAU,CAmOtB"}

package/src/core/model/node-graph/visual/layout/layout_insert_lanes.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"layout_insert_lanes.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/model/node-graph/visual/layout/layout_insert_lanes.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,yEARW,UAAU,GAGR,MAAM,CA8ElB"}

package/src/core/model/node-graph/visual/layout/layout_order_layers.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"layout_order_layers.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/model/node-graph/visual/layout/layout_order_layers.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wEATW,MAAM,UACN,MAAM,GACJ;IAAC,KAAK,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,UAAU,CAAC;IAAC,WAAW,EAAE,UAAU,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAC,CAyJ7F"}

package/src/core/model/node-graph/visual/layout/layout_orient_links.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"layout_orient_links.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/model/node-graph/visual/layout/layout_orient_links.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,qEANW,UAAU,GACR,MAAM,CAkClB"}

package/src/shade/playground/vgeo_viewer/README.md

@@ -1,150 +0,0 @@
-# `.vgeo` viewer
-
-An interactive viewer for the virtual-geometry container. Run the dev server and open it:
-
-```bash
-npm run dev --workspace @woosh/meep-engine
-```
-
-<http://localhost:5173/src/shade/playground/vgeo_viewer/index.html>
-
-Nothing loads by itself. **Drop a `.vgeo` anywhere on the page**, pass `?file=/data/models/…​.vgeo`
-to open one by URL — which is what makes a particular view of a particular asset a bookmark — or
-press **build a sample asset**, which runs the builder in the page over a torus and opens the
-container it produces. `?sample` does the last one on load.
-
-## What is on screen
-
-Not the asset — the **cut**: the clusters the container's own metric selects for where the camera is
-standing, coloured so the seams between them are visible, with the cluster count on screen.
-
-**The cut is frozen until you ask for a new one.** *Adapt to view* re-runs the traversal at wherever
-the camera is now; everything after that is you flying around a decision taken from somewhere else,
-which is the only way to see what a cut actually selected. *Follow the camera* makes it chase
-instead. *tau* is the one quality dial — pixels of permitted error.
-
-Drawing goes through Shade's direct geometry path (a `DynamicMesh` from raw attributes, no meshlet
-encode) because a cut is rebuilt from scratch on every adapt, and it is drawn opaque so the depth
-buffer orders its own triangles.
-
-## What makes it a streaming viewer
-
-The reader under it never holds the whole file. Opening a container reads the header, the level
-table and the root frame — `VGEO_FORMAT.md` §10's always-resident set, two range requests — and
-after that a page arrives only because a traversal asked for it, from exactly the byte range the
-page pointing at it wrote down.
-
-So a cut can be taken before the file has finished arriving, and this is the interesting part: it is
-**clamped, not wrong**. Where the page holding a refinement is missing, the coarser cluster is drawn
-and a *want* is recorded, and the surface is watertight either way.
-
-"Missing" there means §10's *selectable*, not merely resident: a group is refined into only once
-every page holding one of its parents is here. A group's parents are made by one simplification step
-but grouped for the next one separately, so an asset of more than a page per band puts some of them
-in different pages — and refining into a group because its own page arrived, while a coarse cluster
-still stands in for a parent that has not, draws both over the same surface. Those clamps carry no
-want, because there is nothing to fetch from a cluster that already has the bytes it points at; the
-panel counts them under *of those, on a parent*.
-
-Three controls turn that into something you can watch:
-
-| control | what it shows |
-|---|---|
-| **colour by clamp** | amber where the surface is standing in for a page that has not arrived, slate where the cut is the one the file selects |
-| **stream *n* wanted page(s)** | installs eight of them, retakes the cut, repeats — refinement happening in steps rather than in one jump |
-| **evict everything but the root** | back to cold, so it arrives again |
-
-The **streaming** panel is the measurement: `read so far` against the file's own size, the request
-count, what the cold start cost, and how many pages are resident. On anything larger than a toy the
-first of those is a small fraction, and that is the whole claim.
-
-**head prefix** re-opens the current file from cold under a different one. §10 offers a reader two
-cold starts — the 256-byte header and then one exact range per wanted page, or one speculative
-prefix that brings the head and whatever else it happens to cover — and this is the dial between
-them. Coarse-first layout is what makes the second worth doing: a prefix that overshoots the root
-frame has overshot into the pages the traversal is about to want. Watch `read so far` and `requests`
-move against each other. `?head=<bytes>` sets it on load.
-
-**head prefix** on the streaming panel is what is still *held*, and it says `released` for most of a
-session: the reader drops the prefix the first time a read falls outside it, because after the pages
-inside it have installed it is bytes nothing will read — and at a thousand open assets a retained
-256 KiB apiece was a quarter of a gigabyte that neither `resident` nor eviction could see. The
-always-resident set is about 2.4 KB, so the prefix is speculation about the next band and 64 KiB is
-enough of it; the dial is there to watch the trade rather than to tune it.
-
-**quarantined** is the other new row, and it is the difference between an asset that is coarse
-because the camera just moved and one that is coarse because a page will never arrive — which look
-identical on screen. A page that fails its retries is quarantined with its reason and is not asked
-for again; the clamped cut keeps its surface correct with a coarser ancestor, indefinitely.
-
-`read so far` is cumulative and is allowed past 100%: evicting and re-streaming really does fetch
-those pages again, and the audit really does read every byte.
-
-## Validation is optional and off
-
-**Validation is off by default and is not a precondition for anything.** It reads the whole file —
-every frame, every checksum, the directory against a full frame scan — which is exactly what an
-incremental reader exists to avoid, and it answers a question about whoever *wrote* the file rather
-than about the view being put on screen. Press **validate the whole file** when that is the
-question, or pass `?validate`.
-
-It is not a method on the reader, either. `vgeo_audit_container` and `vgeo_install_all_pages` live in
-`format/read/tool/`, and this viewer calls them as the tool it is — a renderer holding a thousand
-containers must not have either within reach of one of them. The audit takes the file as a single
-`ArrayBuffer`, because every build invariant is a cross-check between two places in it, so it refuses
-above 1 GiB naming the size rather than failing in the allocator.
-
-What is *not* optional, because it is the difference between refusing a file and misreading one:
-magic, minimum reader version, payload encoding, hash algorithm, unknown required feature bits,
-unknown codecs, a `decoded_size` outside what the stored bytes could physically produce, and a root
-frame that disagrees with the header about its own size. Those are §4 and §10 reject rules and they
-always run.
-
-**verify each frame's checksum** sits between the two. A frame's identity-seeded checksum covers
-only that frame, so it is verified from bytes just fetched, with no extra request and no whole-file
-pass — §10 requires it of a runtime, where a quarantined page is the difference between a coarse
-stand-in and a wrong surface. Off here for the same reason the audit is: hashing every installed
-byte costs something, and a tool looking at a file it just built is not defending against a network.
-It is read per fetch, so ticking it applies to the next page rather than to a reopen. `?verify` sets
-it on load.
-
-## What lives where
-
-The reader is **not** part of this page. It is `renderer/geometry/virtual/format/read/`, it is the
-shape a runtime would use, and it knows nothing about drawing:
-
-| | |
-|---|---|
-| `VGeoByteSource` | a range at a time, over an `ArrayBuffer` or a dropped `Blob` |
-| `vgeo_fetch_byte_source` | the same over HTTP, refusing a `200` where it asked for a range |
-| `vgeo_read_header` | header and level table, with §4's reject rules |
-| `vgeo_read_page` | one fetched frame → one `VGeoPage`; needs nothing else |
-| `VGeoPage` | a page's own bytes and its own cluster/group/child tables |
-| `VGeoContainerReader` | residency: open, install, evict, and the optional audit |
-| `VGeoDirectory` | the auxiliary page directory, for reaching pages no traversal leads to |
-
-What belongs to the page is everything above the bytes:
-
-| | |
-|---|---|
-| `select_cut.js` | the traversal, the residency clamp, and the wants it records |
-| `cut_geometry.js` | decoding selected clusters into one drawable geometry, and the colour modes |
-| `sample_asset.js` | a container built in the page, so there is something to open |
-| `main.js` | renderer, camera, panel, and the streaming loop |
-
-## Driving it from a script
-
-Everything is reachable from the console, which is what makes the page verifiable in a headless
-browser rather than by a person watching it:
-
-```js
-await __open_sample();       // or __open_url('/data/…​.vgeo')
-__vgeo.set_auto_stream(false);
-__vgeo.reset_residency();    // back to the root page alone
-__state();                   // { resident_pages, bytes_read, clusters, clamped, wants, … }
-await __stream();            // one round of eight pages, then a fresh cut
-await __validate();          // the whole-file audit, as an array of defect strings
-```
-
-`__state()` is the one to assert on: `clamped` reaching zero is the cut having converged on what the
-container selects, and it converges to the same numbers whatever order the pages arrived in.

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

@@ -1,61 +0,0 @@
-/**
- * Decode the selected clusters into one geometry.
- *
- * @param {VGeoCut} cut
- * @param {VGEO_COLOR_MODE} color_mode
- * @returns {VGeoCutGeometry}
- */
-export function vgeo_build_cut_geometry(cut: VGeoCut, color_mode: VGEO_COLOR_MODE): VGeoCutGeometry;
-/**
- * What a cluster's colour is keyed on.
- *
- * The two normal modes are not keyed on the cluster at all: they paint every vertex with its own
- * direction, and the cluster boundaries go with it. `stored normal` is the container's own
- * {@link VGEO_ATTRIBUTE.NORMAL }, decoded out of the payload — the only mode that shows an attribute
- * the file carries rather than something derived from it. `geometric normal` is the area-weighted
- * normal of the decoded triangles, which is what every other mode shades with. The pair is the
- * point: they agree where the builder's normals still describe the geometry it shipped, and a source
- * with no normals at all makes the first one flat.
- *
- * `clamp` is the streaming one: it paints the clusters a coarser page is standing in for, so the
- * regions still waiting on bytes are visible as regions rather than as a number in a panel.
- */
-export type VGEO_COLOR_MODE = string;
-export namespace VGEO_COLOR_MODE {
-    let Cluster: string;
-    let Group: string;
-    let Page: string;
-    let Level: string;
-    let Error: string;
-    let Clamp: string;
-    let StoredNormal: string;
-    let GeometricNormal: string;
-}
-/**
- * A cut, decoded into one geometry.
- *
- * Nothing about it depends on where the camera is: the mesh is drawn solid and the depth buffer
- * orders it, so the triangle list is uploaded once when the cut is taken and never touched again.
- */
-export class VGeoCutGeometry {
-    /**
-     * Position and colour, indexed by {@link triangles}.
-     * @type {Geometry}
-     */
-    geometry: Geometry;
-    /**
-     * `3 · triangle_count` — the full triangle list, in cluster order, and the geometry's index.
-     * @type {Uint32Array}
-     */
-    triangles: Uint32Array;
-    /**
-     * @type {number}
-     */
-    triangle_count: number;
-    /**
-     * @type {number}
-     */
-    vertex_count: number;
-}
-import { Geometry } from "../../renderer/geometry/Geometry.js";
-//# sourceMappingURL=cut_geometry.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"cut_geometry.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/vgeo_viewer/cut_geometry.js"],"names":[],"mappings":"AAqOA;;;;;;GAMG;AACH,kEAHW,eAAe,GACb,eAAe,CAsM3B;;;;;;;;;;;;;;;8BArXS,MAAM;;;;;;;;;;;AA4IhB;;;;;GAKG;AACH;IACI;;;OAGG;IACH,UAFU,QAAQ,CAEQ;IAE1B;;;OAGG;IACH,WAFU,WAAW,CAEU;IAE/B;;OAEG;IACH,gBAFU,MAAM,CAEG;IAEnB;;OAEG;IACH,cAFU,MAAM,CAEC;CACpB;yBA5NwB,qCAAqC"}