@woosh/meep-engine 3.28.0 → 3.29.0

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

@@ -26,27 +26,33 @@ So everything here that the runtime page does not do is about breadth:
 
 ## Running it
 
-Three things: the dev server in front of the page, an asset server in front of the containers, and
-a scene manifest telling the page which is which.
+Two things: a scene manifest under the asset root, and the dev server.
 
 ```
-npm run dev --workspace @woosh/meep-engine
-
 node tools/geometry/virtual/vgeo_scene.js <manifest.vgeo.json> --camera "..." --sun "..."
-node tools/geometry/virtual/vgeo_serve.js <container directory>
+npm run dev --workspace @woosh/meep-engine
 ```
 
-Then open `/src/shade/playground/vgeo_scene/index.html`. With no parameters it asks the asset server
-what it is holding and opens the one scene that is there; `?scene=<url>` overrides.
-
-**The asset server is not optional and vite cannot replace it.** A `.vgeo` is opened out of its head
-and streamed by `Range`, and `vgeo_fetch_byte_source` refuses anything but a `206` naming the range
-it asked for — a `200` is a server ignoring the request and answering the head of the file where the
-reader asked for the middle of a frame, silently and with plausible numbers. Vite also refuses
-`/@fs/` outside the workspace, and a converted scene is tens of gigabytes that has no business
-inside one. `vgeo_serve.js` is ranges, CORS and nothing else; the header that is easy to miss is
-`Access-Control-Expose-Headers`, because a cross-origin response's `Content-Range` is invisible to
-the page without it.
+Then open `/src/shade/playground/vgeo_scene/index.html`. With no parameters it asks the dev server
+for every `.vgeoscene.json` under the roots it is serving and opens the one scene that is there;
+`?scene=<url>` overrides.
+
+**The containers do not have to be in the checkout, and the dev server is what serves them.**
+`tools/dev/vite_test_assets.js` serves `/test_assets/` out of the package's own directory *and* out
+of an external asset root — `MEEP_TEST_ASSETS`, or the nearest `test_assets/` above the package,
+which on this machine is `H:/test_assets` — so Zorah's 51 GiB sit on a drive and are reached at
+`/test_assets/Zorah/…` from the server that is already running. The dev server prints the roots it
+found at startup.
+
+**Ranges are what makes that a claim worth checking.** A `.vgeo` is opened out of its head and
+streamed by `Range`, and `vgeo_fetch_byte_source` refuses anything but a `206` naming the range it
+asked for — a `200` is a server ignoring the request and answering the head of the file where the
+reader asked for the middle of a frame, silently and with plausible numbers. That invariant is
+`tools/dev/serve_file_range.js` and there is one of it:
+`tools/geometry/virtual/vgeo_serve.js` — still the answer for a directory under no asset root, or a
+page served from another origin — is the same code plus CORS, where
+`Access-Control-Expose-Headers` is the header that is easy to miss, because a cross-origin
+response's `Content-Range` is invisible to the page without it.
 
 ## What a scene manifest is, and what it is not
 
@@ -170,10 +176,80 @@ counted as `instances_dropped` while the collection caught up.
   folds a negative determinant into a scale axis, so a reflection survives. This is a property of
   the engine's transform model rather than of this page. The reflections surviving is what the next
   section is about.
-- **One material for the whole scene.** Not a simplification being made here: a `.vgeo` carries
-  geometry only, so the source's 2,714 materials did not survive a conversion that never asked them
-  to. Tinting each container would read better, would be a lie about where the colour came from, and
-  would put 2,714 material buckets in front of the draw path to say it with.
+- **A material's texture, when it has one.** The containers have no texture coordinates — see the
+  next section — so a material is bound as the constants its textures average to rather than as the
+  textures themselves.
+
+## Materials, and why they arrive from the side
+
+A `.vgeo` carries geometry only, so a converted set has no material authoring in it. For a long time
+this page drew all of it with one grey material and said so here, because the alternative was
+inventing colour.
+
+It now reads a **sidecar** instead: `<scene>.vgeomaterials.json`, written by
+[`vgeo_scene_materials.js`](../../../../../tools/geometry/virtual/vgeo_scene_materials.js) out of an
+extraction of the original Unreal project
+([`tools/ue/`](../../../../../tools/ue/)). It says which material each container is — a `.vgeo` is
+one glTF primitive and a primitive has exactly one material, so the container *is* the bucket — and
+what to shade that material with. It is a separate file from the scene manifest because it answers
+to a separate source, and a scene nobody has extracted a project for is still a scene: the page
+opens with or without one.
+
+`?materials=off` refuses it and restores the one-grey-material picture. `?materials=<url>` names one
+explicitly.
+
+**What is bound is the constants, not the textures, and that is about the asset.**
+`zorah_main_public.v2.gltf` — the document every container was built from — declares `POSITION` and
+nothing else. No `TEXCOORD_0`, no `NORMAL`; the normals and tangents in the containers were generated
+during conversion. So there is nothing to sample an albedo map *with* until a UV-carrying source is
+built and the containers are made again from it. The constants are measured rather than invented:
+`albedo` is the extracted base colour map's own alpha-weighted mean **in linear space**, multiplied
+by the material's authored tint; roughness comes from the real ORM and metalness from the same map,
+rounded, because metalness is binary per texel and the mean of a map is not a metalness. What a
+surface loses is its detail, not its identity.
+
+**The numbers, for Zorah.** 341 material names, of which 146 are in the distributed Unreal sample —
+it ships a subset of the scene the glTF came from, and 191 of the names are nowhere in it. 72 more
+are drawn as the nearest sibling within a narrow family and say so in `approximated_from`. That is
+**218 materials over 2,533 of the 3,163 containers**; the remaining 630 draw as a neutral grey.
+
+**They cost about 2.4 ms.** Measured on an nvidia/lovelace adapter at 1578×746 from the authored
+viewpoint, twelve samples each: **5.28 ms** median with one material, **7.7 ms** with 218. That is
+the scene's real shape rather than a price this page chose to pay, and it is worth knowing that a
+material bucket is not free — about eleven microseconds of one, here.
+
+## The indirect light is brighter than the light
+
+Extracted materials read paler and less saturated than the maps they came from, and the reason is
+not in the materials. `?env=` and `?sun=` are here to say so in one measurement.
+
+`?env=uniform:<v>` replaces the sky with a **constant radiance from every direction** — 64×64 so it
+carries a mip chain, every level the same value — and `?sun=off` takes the only other light away.
+Against a uniform environment the question is closed rather than arguable: nothing can return more
+of a constant field than it reflects.
+
+Measured on the `waterjug` sample at `env=uniform:0.5&sun=off&textures=off`, one pixel of the
+surface against one pixel of the background, in the same frame and therefore at the same exposure:
+
+| material | surface ÷ environment | should be |
+|---|---:|---:|
+| albedo 0, roughness 0.57 | **2.74** | ~0.05 |
+| albedo 0, roughness 1.0 | **2.69** | ~0.05 |
+| albedo 0.18 | 3.06 | ~0.23 |
+| albedo 1.0 | 4.49 | ~1.0 |
+
+**A black, non-metal surface returns 2.7× the only light in the scene.** Tonemapping is monotonic,
+so no curve makes that legitimate — it is energy gain, and it is what puts a constant neutral
+pedestal under every material and washes the colour out of it. It is independent of albedo, of
+roughness, and of the sun; `?env=off` removes it entirely.
+
+`indirect_specular` is `radiance * totalScattering` and radiance here is 0.5 by construction, so
+`totalScattering` is coming out near 2.7. `compute_multiscattering_specular` cannot produce that
+from a sane split-sum lookup, so the gain is above it — the LUT's own values, `specular_occlusion`,
+or the specular IBL pass. Not chased further than that.
+
+**None of this is about virtual geometry**, which is why it is a note rather than a fix here: it
+reproduces with a constant-colour `StandardShadeMaterial` and no extraction involved.
 
 ## Reflected instances — the bug this page was built to show, and where it went
 
@@ -388,13 +464,16 @@ the scene's counts, the cut's counters, both residency tiers, the render target'
 camera. `__page.runtime.tau` is the threshold, `__look(eye, target)` stands the camera somewhere,
 and `__page.viewpoints` is what the buttons in the panel are.
 
-URL parameters, all of them for a session rather than for a person: `?scene=` the manifest,
+URL parameters, all of them for a session rather than for a person: `?scene=` the manifest (any
+URL, and `/test_assets/…` is the asset root),
 `?tau=` the threshold **before the first container** (see the table above for why a load per row),
 `?pages=` the VRAM tier's slots, `?iterations=` the descent's wavefront ceiling,
 `?eye=x,y,z&at=x,y,z` a viewpoint, `?side=front|back|double` the whole scene's draw side,
-`?mirrored=flip|tint|double` the reflected instances' — and `?catch=<fraction>[&freeze=1]` the
-dropout catcher. `__state().scene.mirrored` is the reflected count the panel shows, and `__caught()`
-the catcher's report.
+`?mirrored=flip|tint|double` the reflected instances', `?materials=off|<url>` the material sidecar,
+`?textures=off` its maps, `?env=off|uniform:<v>` and `?sun=off` the lighting —
+and `?catch=<fraction>[&freeze=1]` the dropout catcher. `__state().scene.mirrored` is the reflected
+count the panel shows, `__state().scene.materials` and `.materialised` the material counts, and
+`__caught()` the catcher's report.
 
 **`T` records a GPU capture and `T` again downloads an `.sgpt`** — the same key and the same module
 (`playground/profile_hotkey.js`) every other playground binds. It answers the question the panel