@woosh/meep-engine 3.20.0 → 3.22.0

package/src/shade/playground/particle_system/particle_scene.js

@@ -11,7 +11,6 @@ import { make_sunlight } from "../../renderer/light/make_sunlight.js";
 import { ShadeDrawSide } from "../../renderer/material/ShadeDrawSide.js";
 import { StandardShadeMaterial } from "../../renderer/material/StandardShadeMaterial.js";
 import { TransparencyMode } from "../../renderer/material/TransparencyMode.js";
-import { PARTICLE_COUNTER_COUNT } from "../../renderer/particles/data/PARTICLE_COUNTERS.js";
 import { EMITTER_BLEND, EMITTER_PROJECTION } from "../../renderer/particles/data/PARTICLE_EMITTER_STRUCT.js";
 import { particle_node, particle_wire } from "../../renderer/particles/graph/particle_graph_authoring.js";
 import {
@@ -54,25 +53,6 @@ import { fire_effect } from "./particle_prototype.js";
  * - a sunlight and (from the page) the default environment, because the meshes are lit.
  */
 
-/** Bytes {@link encode_stats_copy} writes: 8 counters, then both indirect arg buffers. */
-export const PARTICLE_STATS_BYTES = 64;
-
-const STATS_OFFSET_DISPATCH_ARGS = 32;
-const STATS_OFFSET_DRAW_ARGS = 48;
-
-/**
- * @typedef {object} ParticleSceneStats
- * @property {number} alive particles alive at the end of the captured frame
- * @property {number} dead free slots left in the pool
- * @property {number} spawn_budget free slots the frame's emitters left unclaimed
- * @property {number} alive_in the snapshot next frame's simulate reads as its input length — the
- *   PADDED length of the coherence list, so it is `sim_padded` from the captured frame, not `alive`
- * @property {number} sim_padded length of the program-coherent list the coherence pass built this
- *   frame; the gap to `alive` is the lanes padding costs to keep each wave on one VM program
- * @property {number[]} dispatch simulate's indirect dispatch args, `[x, y, z]` workgroups
- * @property {number[]} draw the draw's indirect args, `[vertices, instances]`
- */
-
 /**
  * What each of the four parametric emitters emits, apart from the fire, whose effect is the worked
  * example next door. Exported so the page can show what each emitter is doing.
@@ -272,44 +252,6 @@ export function animate_particle_scene(emitters, time) {
     orbit.updateMatrices();
 }
 
-/**
- * Copy the counters and both indirect arg buffers into a {@link PARTICLE_STATS_BYTES}-byte
- * MAP_READ destination, for display. Read back to *look at*: nothing here may size a pass.
- *
- * @param {import("../../renderer/particles/GPUParticleSystem.js").GPUParticleSystem} system
- * @param {GPUCommandEncoder} encoder
- * @param {GPUBuffer} destination
- */
-export function encode_stats_copy(system, encoder, destination) {
-    const buffers = system.buffers;
-
-    encoder.copyBufferToBuffer(buffers.counters, 0, destination, 0, PARTICLE_COUNTER_COUNT * 4);
-    encoder.copyBufferToBuffer(buffers.dispatch_args, 0, destination, STATS_OFFSET_DISPATCH_ARGS, 3 * 4);
-    encoder.copyBufferToBuffer(buffers.draw_args, 0, destination, STATS_OFFSET_DRAW_ARGS, 4 * 4);
-}
-
-/**
- * Interpret the bytes {@link encode_stats_copy} wrote.
- *
- * @param {ArrayBuffer} bytes
- * @returns {ParticleSceneStats}
- */
-export function read_stats(bytes) {
-    const words = new Uint32Array(bytes);
-    const dispatch_base = STATS_OFFSET_DISPATCH_ARGS / 4;
-    const draw_base = STATS_OFFSET_DRAW_ARGS / 4;
-
-    return {
-        alive: words[0],
-        dead: words[1],
-        spawn_budget: words[2],
-        alive_in: words[4],
-        sim_padded: words[5],
-        dispatch: [words[dispatch_base], words[dispatch_base + 1], words[dispatch_base + 2]],
-        draw: [words[draw_base], words[draw_base + 1]],
-    };
-}
-
 /**
  * A 64x64 radial-falloff sprite (white, alpha falloff) for soft additive and alpha blobs.
  *

package/src/shade/playground/skinned_blas_refit/sweep_views.js

@@ -59,7 +59,7 @@ export async function sweep_views({
     const radius = Math.hypot(box[3] - box[0], box[4] - box[1], box[5] - box[2]) * 0.5;
 
     const kept = {
-        position: [...camera.transform.position],
+        position: [...camera.transform.translation],
         near: camera.near,
         far: camera.far,
     };
@@ -101,7 +101,7 @@ export async function sweep_views({
                 largest: result.largest_components[0] ?? 0,
                 median: result.median_component,
                 converging: result.still_converging,
-                position: [...camera.transform.position].map(v => +v.toFixed(3)),
+                position: [...camera.transform.translation].map(v => +v.toFixed(3)),
             });
         }
     }

package/src/shade/playground/skinned_blas_refit/verify_traversal_reachability.js

@@ -141,7 +141,7 @@ export async function verify_traversal_reachability({
 
     const origin = inverse_transform_point(
         mesh.transform_global.matrix,
-        [...camera.transform.position]
+        [...camera.transform.translation]
     );
 
     const t_bytes = leaf_count * Float32Array.BYTES_PER_ELEMENT;

package/src/shade/playground/ssr_variance/reference.d.ts

@@ -12,7 +12,7 @@ export class ReflectionReference extends RenderExtension {
     textures: any[];
     device: any;
     record(frame: any): void;
-    read(): Promise<TypedArray>;
+    read(): Promise<import("../../../core/primitives/TypedArray.js").TypedArray>;
 }
 import { RenderExtension } from "../../renderer/extension/RenderExtension.js";
 //# sourceMappingURL=reference.d.ts.map

package/src/shade/playground/ssr_variance/reference.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reference.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/ssr_variance/reference.js"],"names":[],"mappings":"AA8DA;;;;;EAeC;AAjDD,yFAAyF;AACzF;IAKI,yBAAsD;IAHtD,iBAAgB;IAChB,cAAU;IACV,gBAAc;IACiB,YAAoB;IACnD,yBAmBC;IACD,4BAIC;CACJ;gCA5D+B,6CAA6C"}
+{"version":3,"file":"reference.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/ssr_variance/reference.js"],"names":[],"mappings":"AA8DA;;;;;EAeC;AAjDD,yFAAyF;AACzF;IAKI,yBAAsD;IAHtD,iBAAgB;IAChB,cAAU;IACV,gBAAc;IACiB,YAAoB;IACnD,yBAmBC;IACD,6EAIC;CACJ;gCA5D+B,6CAA6C"}

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

@@ -0,0 +1,132 @@
+# `.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.
+
+`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`.
+
+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

@@ -0,0 +1,61 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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"}