@woosh/meep-engine 3.60.4 → 3.60.6

package/src/shade/RENDERER_CONTRACT.md

@@ -1,697 +0,0 @@
-# The renderer contract
-
-meep 3.0 has one renderer, and this is what it promises.
-
-It is written for somebody who has never seen the inside of it: by the end of §3 you have a model on
-the screen, and by the end of §6 you have your own work in the frame. Everything here is the public
-surface — the types you construct, the calls you make, and the two or three places where the answer
-is "no, and here is why".
-
-If you are looking for how it works rather than what it promises, the design documents are next to
-the code they describe: `renderer/extension/RENDER_EXTENSION_DESIGN.md`,
-`renderer/geometry/virtual/VIRTUAL_GEOMETRY_DESIGN.md`, `renderer/geometry/meshlet/README.md`,
-`renderer/NOTES.md`.
-
----
-
-## 1. What it is
-
-A **GPU-driven, visibility-buffer deferred renderer on WebGPU.** Geometry is clustered into meshlets
-ahead of time and lives in one large GPU buffer; culling runs on the GPU; the rasterizer writes a
-visibility buffer and a G-buffer rather than shading as it draws; lights are binned into froxels and
-applied deferred; and the result is temporally resolved, upscaled, tonemapped and presented.
-
-Three consequences that shape everything below:
-
-- **A mesh is a small GPU-resident record, not a draw call you own.** You place a model at entities
-  of the scene's dataset and each primitive is a row; what is drawn, in what order, and whether it
-  is culled is the renderer's.
-- **Preparing geometry is a precompute.** Meshlet building, encoding and BVH construction happen
-  once per geometry. Content that rewrites its vertices every frame goes down a separate path (§8).
-- **The frame is a closed sequence with declared injection points.** You do not insert a pass
-  anywhere; you register an extension against a phase (§6).
-
-### What is deliberately absent
-
-| | |
-|---|---|
-| **No RHI, no backend abstraction** | There is one target, WebGPU. There is no seam where a second one would go, and adding one is not a small change. |
-| **No WebGL fallback** | Below-floor hardware gets a clean failure message (§2), not a degraded picture. |
-| **No degradation tiers** | There is one pipeline. Individual features can be switched off (`feature_shadows_enabled`, `feature_taa_enabled`, the resolution scale), but there is no "low quality" build of the frame. |
-| **No compressed textures** | DDS, Draco and Basis are not supported anywhere. glTF files carrying `MSFT_texture_dds` load from their base PNG source. |
-
----
-
-## 2. The device floor
-
-The renderer requires a WebGPU device that meets a fixed floor. There is no feature detection
-beyond it and no branch that produces a lesser frame.
-
-**Required features** — the adapter must have all three, or startup fails:
-
-- `indirect-first-instance` — indirect draw is used throughout
-- `float32-blendable` — the MBOIT transparency mode blends into 32-bit float targets. The default mode,
-  AVBOIT, blends `rgba16float` only and does not need it. The feature stays on the floor while MBOIT is
-  selectable at all; retiring it from the floor means retiring MBOIT.
-- `texture-formats-tier1` — the hierarchical Z buffer is reduced in compute into `rg16float` storage
-  textures, which core WebGPU cannot write. Without it the HZB texture and every HZB pipeline fail
-  validation, and occlusion culling, SSR, screen-space shadows and light culling all read the HZB.
-
-**Required limits:**
-
-- `maxStorageBuffersPerShaderStage` ≥ **10**
-- `maxColorAttachmentBytesPerSample` ≥ **32** — the G-buffer is wide
-- `maxBufferSize` and `maxStorageBufferBindingSize` are requested at whatever the adapter offers,
-  because the defaults are far too small
-
-The required features and the two fixed limits are one definition, `device/SHADE_DEVICE_FLOOR.js`.
-All of it is checked against the adapter before a device is requested, so a refusal names every
-feature and limit the adapter lacks, with the value it offers, rather than the first one found.
-
-**Taken when offered, never required:** `timestamp-query`, `subgroups`.
-`timestamp-query` drives GPU timers and nothing else, and some browsers withhold it on hardware that
-is otherwise fine — so the timers go quiet when it is absent rather than the renderer refusing to
-start.
-
-### When it is not met
-
-`Renderer.initialize()` throws a `ShadeDeviceFailure`, whose `message` is written to be shown to a
-person rather than logged. It distinguishes:
-
-| | |
-|---|---|
-| `webgpu_unavailable` | no `navigator.gpu` — WebGPU disabled or unsupported |
-| `adapter_unavailable` | no adapter at all |
-| `below_floor` | an adapter that does not meet §2; the message lists every unmet feature and limit |
-| `device_request_failed` | the adapter refused the device |
-| `device_lost` | a working device went away while running |
-
-A device lost while running arrives on `Renderer.onDeviceFailure` instead of being thrown. **The
-renderer does not recover a lost device.** Everything it built lived on it, and the honest response
-is a message and a reload. The signal exists so an application can say so and save what it has.
-
----
-
-## 3. Putting a model on the screen
-
-meep has no module aliases: every import is a relative path, and the ones below are written from
-`src/shade/` so they read like the tree in §10.
-
-```js
-import { Renderer } from "./renderer/Renderer.js";
-import { Scene } from "./renderer/scene/Scene.js";
-import { PerspectiveCamera } from "./renderer/camera/PerspectiveCamera.js";
-import { make_sunlight } from "./renderer/light/make_sunlight.js";
-import { place_light } from "./renderer/light/place_light.js";
-import { EntityComponentDataset } from "../engine/ecs/EntityComponentDataset.js";
-import { Transform64 } from "../engine/ecs/transform/Transform64.js";
-import { prefab_compile } from "../engine/graphics3/prefab/prefab_compile.js";
-import { prefab_place } from "../engine/graphics3/prefab/prefab_place.js";
-import { load_gltf } from "./renderer/loader/gltf/load_gltf.js";
-import { create_frame_loop } from "./renderer/create_frame_loop.js";
-import { DEG_TO_RAD } from "../core/math/DEG_TO_RAD.js";
-import Vector3 from "../core/geom/Vector3.js";
-
-const canvas = document.querySelector("canvas");
-
-const renderer = new Renderer();
-
-await renderer.initialize({ context: canvas.getContext("webgpu") });
-
-const camera = new PerspectiveCamera();
-
-camera.transform.position.set(0, 2, -5);
-camera.transform.lookAt(Vector3.zero);
-camera.near = 0.1;
-camera.far = 200;
-camera.fov = 72 * DEG_TO_RAD;
-camera.aspect = renderer.aspect_ratio;
-
-const scene = new Scene();
-
-// everything in a scene stands at an entity, so the scene names a dataset — a map of components,
-// no systems
-scene.dataset = new EntityComponentDataset();
-
-// nothing is lit without one, and the deferred shading pass has no default light
-place_light(scene, make_sunlight({ intensity: 2.2 }));
-
-const bundle = await load_gltf("model.glb", { assetManager });
-
-// the model as loaded is compiled once; a placement of it is entities of the dataset, one per node
-// of the file, each with a row of the scene's GPU database — the scene's context is where the rows
-// live
-prefab_place(renderer.scenes.obtain(scene), scene.dataset, prefab_compile(bundle), new Transform64());
-
-create_frame_loop(dt => renderer.render(camera, scene, dt));
-```
-
-That is the whole of it. Five things in it are worth stating outright.
-
-**`initialize` is asynchronous and may fail normally.** Acquiring a WebGPU device has no synchronous
-form and being refused one is an ordinary outcome, so it is a rejected promise carrying a
-`ShadeDeviceFailure` rather than a constructor that throws. Omit `context` and a full-viewport canvas
-is created for you; pass a `device` to share one you already have.
-
-**`assetManager` is required, and here is where one comes from.** A glTF is several files — a
-container, its `.bin` buffers, its images — and which of them are already in memory is not the
-parser's business to know. Every request the parse makes goes back through the manager, so they are
-cached, counted and cancellable like anything else the application loads. Two loaders are all
-`load_gltf` asks for:
-
-```js
-const assetManager = new AssetManager({ context: {}, executor: new ConcurrentExecutor() });
-
-await assetManager.registerLoader(GameAssetType.ArrayBuffer, new ArrayBufferLoader());
-await assetManager.registerLoader(GameAssetType.ImageBitmap, new ImageBitmapAssetLoader());
-
-assetManager.startup();
-```
-
-Pass a `scope` alongside it to tie a whole load to one cancellable unit, and a `fileMap` when the
-files come from a drop rather than from the network. An application already running meep's `Engine`
-has a configured manager on it and should use that one.
-
-**A model does not have to come from a file.** Everything `load_gltf` produces you can build
-directly, which is §4 in the other direction and needs no asset manager at all:
-
-```js
-const transform = new Transform64();
-
-transform.setTranslation(0, 1, 0);
-transform.updateMatrix();
-
-place_primitive(
-    renderer.scenes.obtain(scene),
-    meshlet_geometry_build_from_geometry(make_torus_knot_geometry(1, 0.3, 128, 16)),
-    new StandardShadeMaterial(),
-    transform
-);
-```
-
-**`render` returns a boolean.** `false` means the previous frame has not finished and this one was
-not submitted. It is not an error.
-
-**Everything drawn or posed is an entity of the scene's dataset, holding a row of the scene's GPU
-database.** `prefab_place` answers what it placed — the root entity, the instance, its animation
-registration — and `prefab_unplace` takes it all back; `place_primitive` answers the entity,
-`move_primitive` moves it and `remove_primitive` takes it back. A game calls none of them: its
-systems take rows as components appear. A light is the same shape — it stands at an entity, and
-`scene.lights.add(light, entity)` — `place_light(scene, light)`, for a caller with no entity of its
-own — is what puts it in the scene. Its record's pose is that entity's row, read on the GPU every
-frame.
-
----
-
-## 4. The type model
-
-Everything in a scene is an **entity** of the scene's dataset, and what the renderer knows about it
-is **a row** of the scene's GPU database, at `entity + 1` in two tables: `transforms` — its local TRS
-and the row of its parent — and, for a primitive, `meshes` — which geometry, which material, and the
-world bounds. Row 0 is the scene root, identity. There is no CPU object per node, no parent pointer
-to follow and no world matrix to recompose: the GPU composes every chain each frame, from the rows,
-and derives every mesh row's bounds under the composed matrix.
-
-**An entity is placed through its `Transform64`, and what the GPU holds is derived from it.** A
-root entity's row carries its world pose; an entity attached under another (`TransformAttachment`)
-carries its local offset and names its parent's row. A game's systems write these as components
-change; a scene with no systems places through `prefab_place` and `place_primitive`, and moves a
-primitive through `move_primitive`, which marks the row for the next build. The box that is drawn
-is the GPU's — `GPUSceneContext.bounds` reads it back, a frame or two behind — and nothing on the
-CPU keeps a copy of it.
-
-**An entity's transform and a camera's are different types, deliberately, and this is the one place
-a newcomer will trip.** `Transform64` is a flat `Float64Array` holding its own matrix, posed through
-`setTranslation(x, y, z)` / `setRotation(x, y, z, w)` / `setScale(x, y, z)` and refreshed with
-`updateMatrix()`, with the buffer layout part of its contract so hot code can write it directly. A
-`Camera` is **not** an entity — it carries meep's ECS `Transform`, whose `position`, `rotation` and
-`scale` are observable vectors you assign into. The two keep distinct shapes on purpose and neither
-has the other's accessors: `transform.position` is `undefined` on a `Transform64`, and so is
-`camera.transform.translation`.
-
-```js
-transform.setTranslation(0, 1, 0);         // Transform64 — then updateMatrix()
-camera.transform.position.set(0, 2, -5);   // Transform    — reactive, no refresh call
-```
-
-```
-Scene
-├── dataset             EntityComponentDataset — every entity the scene draws or poses; its rows
-├── lights              LightCollection        — each at an entity; their own pipeline, not a mesh row
-├── light_probe_volume
-└── volumetrics
-```
-
-A **primitive** is an entity holding a `meshes` row. Its `ShadedGeometry` component names what the
-row draws, so a tool can read it back:
-
-```js
-geometry  // MeshletGeometry — what to draw
-material  // ShadeMaterial   — how to draw it
-```
-
-and the row carries the world-space `bounding_box` / `bounding_sphere` the renderer derives for
-culling.
-
-### Geometry: two types, one of which is a precompute
-
-**`Geometry`** is the authoring form: named `Attribute`s over typed arrays, an optional index, a
-`bounding_box`/`bounding_sphere` computed on demand by `ensureBounds()`, and a `version` you bump
-through `needsUpdate = true` when you rewrite the arrays. Attributes are read by name:
-
-```js
-geometry.getAttribute(StandardAttributes.Position).data   // Float32Array
-geometry.index.data                                       // Uint32Array
-```
-
-Ten generators ship, all returning a `Geometry`, in `renderer/geometry/primitives/`:
-`make_box_geometry`, `make_plane_geometry`, `make_polyhedron_geometry`, `make_octahedron_geometry`,
-`make_uv_sphere_geometry`, `make_capsule_geometry`, `make_cylinder_geometry`, `make_cone_geometry`,
-`make_torus_geometry`, `make_torus_knot_geometry`.
-
-**`MeshletGeometry`** is the GPU form: triangles clustered into meshlets, attributes encoded, and a
-BVH over the clusters. This is what a mesh row names, and it is what buys cluster culling and a
-compact residency.
-
-```js
-const meshlets = meshlet_geometry_build_from_geometry(geometry);
-```
-
-**That build is a precompute.** Do it once, when the content is created or loaded. If your vertices
-change every frame, you are on the wrong path — see §8.
-
-Seven of the primitives also come ready built, as `MeshletGeometry` subclasses one per module in
-`renderer/geometry/`: `BoxGeometry`, `PlaneGeometry`, `UVSphereGeometry`, `CapsuleGeometry`,
-`CylinderGeometry`, `ConeGeometry` and `TorusGeometry`. Each constructor runs its generator and then
-this build, so constructing one is the same precompute.
-
-### Materials
-
-`ShadeMaterial` is the base: `transparency_mode`, `draw_mode` and `draw_side`.
-
-**`draw_side` changes what is drawn.** `Front` (the default) draws the front face, `Back` the back
-face, `Double` both. A face seen from behind is shaded with its normal flipped, so `Double` is a
-working double-sided material and not a hint. glTF `doubleSided: true` arrives as `Double` and
-stays that way; glTF cannot ask for `Back`, which comes from authoring.
-
-**Only `Double` costs a pipeline of its own.** It culls nothing, and no amount of winding expresses
-that. `Front` and `Back` differ by winding alone, and the vertex shader reverses winding per
-instance, so the two share a rasterization bucket and draw in one pass — which matters because a
-bucket is not a pipeline here but a whole chain: extract, expand to meshlets, select a
-virtual-geometry cut, one render pass.
-
-**That is also why a mirrored instance works.** Place a mesh under a negative scale, or under a
-parent that reflects, and it draws right way out, with the handedness of its tangent frame flipped
-to match — the reflection and the material's side are the same one bit, combined before a corner is
-chosen. glTF makes this the rule rather than an extra: the determinant of a node's world transform
-decides its winding, and a conformant renderer has to read it.
-
-Shadow passes cull the other face — so a one-sided surface casts from its back face and does not
-shadow-acne against its own lit side. `Double` has no opposite and stays unculled in both.
-
-`StandardShadeMaterial` is the PBR one everything uses:
-
-| | |
-|---|---|
-| `texture_albedo` | base colour, alpha carries transparency |
-| `diffuse_color` | multiplied with the albedo |
-| `texture_normal` | tangent-space normals |
-| `texture_orm` | occlusion / roughness (G) / metalness (B), as glTF packs it |
-| `texture_emissive`, `emissive_factor` | |
-| `roughness_factor`, `metallic_factor` | multiplied with the ORM texture |
-| `transmission_factor`, `ior_factor` | |
-| `ambient_factors` | a `LinearModifier` over the indirect contribution |
-| `vt_stack` | opt-in virtual texturing; when set, albedo/normal/ORM come from streamed pages instead. Opaque materials only |
-
-### Textures
-
-Two objects, and the split matters: **`ShadeImage`** is the pixels, **`ShadeTexture`** is how to
-sample them. Two materials sampling one image differently are two textures over one image, and the
-image is uploaded once.
-
-```js
-const image   = ShadeImage.fromImageBitmap(bitmap);   // or fromSampler2D, or fromArrayBuffer
-const texture = ShadeTexture.from(image);
-
-texture.wrapS = TextureWrapType.Repeat;
-texture.magFilter = TextureFilterType.Linear;
-```
-
-`ShadeTexture` carries filters, wrap modes and flags (mipmap generation is on by default), and both
-types answer `equals`/`hash`, which is what lets the renderer de-duplicate uploads.
-
-### What a glTF becomes
-
-`load_gltf` returns a **`SceneBundle`** — three arrays out of the one file:
-
-```js
-bundle.nodes    // SceneNode[]          — the file's nodes in pre-order: name, parent, local TRS, geometry, material
-bundle.skins    // Skin[]               — joints and meshes as indices into nodes
-bundle.clips    // ShadeAnimationClip[] — each channel targets an index into nodes
-bundle.lights   // {light, node}[]      — anchored by index
-```
-
-The bundle is **the model as loaded, not a placement of it** — records, with no transform state
-anyone could pose. It is compiled once into a `Prefab` (`prefab_compile`), and every placement is
-spawned from that — `prefab_place` in a scene with no systems, `prefab_instantiate` under a game's
-own root entity — with its own entities, its own skins and its own retargeted clips, addressed by
-entity, which is what makes two of one model possible.
-
----
-
-## 5. The frame
-
-```
-FrameStart          view updated, nothing rasterized
-   ↓
-[ visibility buffer + G-buffer ]
-AfterGBuffer        surface properties written and readable, nothing lit
-   ↓
-[ clustered lighting, deferred shading, volumetrics ]
-AfterLighting       opaque lit and composited
-   ↓
-[ transparency ]
-AfterTransparency   the complete scene, HDR, internal resolution
-   ↓
-[ TAA / NSS upscale ]  ← resolution changes here
-BeforePresent       HDR, output resolution, immediately before tonemapping
-   ↓
-[ tonemap → canvas ]
-Overlay             display space, drawing onto the canvas
-```
-
-**The upscale is a phase boundary and it is the one thing about the frame you cannot assume away.**
-Three phases are before it and two are after. With `feature_taa_enabled === false` there is no
-upscale and the two sides are the same size. Nothing in this document states a resolution as a
-constant: ask `frame.resolution`, which is derived from the live handle and is right in every
-configuration, including under dynamic resolution scaling.
-
----
-
-## 6. Adding your own work to the frame — render extensions
-
-An extension is **a named object with declarations and one method**.
-
-```js
-import { RenderExtension } from "./renderer/extension/RenderExtension.js";
-import { FramePhase } from "./renderer/extension/FramePhase.js";
-import { SceneColor } from "./renderer/extension/SceneColor.js";
-import { ViewTextures } from "./renderer/extension/ViewTextures.js";
-
-class PathExtension extends RenderExtension {
-    name = "path display";
-
-    phase = FramePhase.AfterTransparency;
-
-    record(frame) {
-        if (this.#batch.count === 0) {
-            // nothing to draw, and the frame's colour is left exactly as it was
-            return;
-        }
-
-        const scene = frame.get(SceneColor);
-        const view = frame.get(ViewTextures);
-
-        const drawn = this.#renderer.graph_draw({
-            graph: frame.graph,
-            batch: this.#batch,
-            color: scene.color,
-            depth: view.depth,
-            camera: frame.view.camera.buffer
-        });
-
-        scene.color = drawn.color;
-        view.depth = drawn.depth;
-    }
-}
-
-const registered = renderer.add_extension(new PathExtension());
-// ...
-renderer.remove_extension(registered);
-```
-
-That is the whole mechanism. The rest of this section is what the four lines of it mean.
-
-**An extension draws over transparency, never inside it.** At `AfterTransparency` the transparent
-surfaces are already resolved into the colour, so what an extension draws there covers them whatever
-their depth. Content that has to sit among transparent surfaces — in front of some, behind others —
-is a transparency channel instead (§8).
-
-### Records are the channel
-
-`record(frame)` **returns nothing.** Everything an extension exchanges with the frame goes through
-typed **records**: you read a frame-graph handle out of one and write a replacement back, and
-**writing a field is publication** — everything after you carries what you left.
-
-There is no privileged resource. The scene colour is published exactly the way a G-buffer target is,
-and exactly the way a record of your own is.
-
-| record | carried at | writable |
-|---|---|---|
-| `SceneColor` — `.color`, HDR | `AfterLighting` … `BeforePresent` | yes |
-| `GBufferTextures` — `.albedo` (AO in alpha), `.normal`, `.pbr`, `.emissive` | `AfterGBuffer` … `BeforePresent` | **`AfterGBuffer` only** |
-| `ViewTextures` — `.depth`, `.depth_previous`, `.visibility_mesh`, `.visibility_triangle` | `AfterGBuffer` … `BeforePresent` | yes |
-| `PresentTarget` — `.canvas` | `Overlay` only | yes |
-
-Three of those rows are the whole reason phases exist:
-
-- **`SceneColor` is not carried at `Overlay`.** A texture may not be a render attachment and a
-  sampled source in the same pass, so at `Overlay` the canvas is written and cannot be read. An
-  effect that needs the finished image as *input* — a colour grade, a full-screen re-composite —
-  belongs at `BeforePresent`. You find that out from `frame.get(SceneColor)`, which fails with a
-  sentence naming the phases that do carry it, rather than from a `-1` failing inside a binding
-  builder.
-- **`GBufferTextures` is in/out at `AfterGBuffer` and frozen afterwards.** Changing surface
-  properties means reading the targets, writing replacements and publishing the new handles — two of
-  the four are integer formats and cannot be blended, and nothing can be attachment and source at
-  once. It stays *readable* to `BeforePresent` because outline and selection effects legitimately
-  read it late; at that phase it is on the far side of the upscale and is therefore **a different
-  size from the colour beside it**. `frame.describe(handle)` is how a pass working across that
-  boundary learns the ratio.
-- **`PresentTarget` has one field and is not called `SceneColor` on purpose.** There is no colour
-  there to be tempted by. Keep the existing contents with a `load` op, write only your own pixels,
-  and publish the result back — that is what lets two overlay extensions compose.
-
-### Extending the vocabulary
-
-An extension can publish a record of its own for another extension to read, and doing so costs no
-edit to the renderer:
-
-```js
-class VisibilityGrid extends FrameRecord {
-    #grid = -1;
-
-    static is_present_at(phase) { return true; }
-
-    get grid() { return this.read(this.#grid); }
-    set grid(handle) { this.#grid = this.publish(handle); }
-}
-
-// at FrameStart
-frame.create(VisibilityGrid).grid = record_the_grid_update(frame.graph);
-
-// at AfterTransparency, in another extension
-if (frame.has(VisibilityGrid)) { … frame.get(VisibilityGrid).grid … }
-```
-
-`has` / `get` / `create` are three calls rather than one `get_or_create` because **absent has to stay
-distinguishable from empty.**
-
-### Ordering
-
-Order is **declared**, never emergent:
-
-```js
-class DecalExtension extends RenderExtension {
-    phase = FramePhase.AfterGBuffer;
-    relative_order = 1;   // a decal composites over surfaces already written
-}
-```
-
-`relative_order` defaults to `0`; lower records first, and any finite number will do — negative to
-pull forward, positive to push back. Two extensions on one phase with the same value record in
-**ascending `name` order**, which is reproducible rather than correct and is chosen precisely so
-that adding an `await` to a system's startup cannot change the picture.
-
-**It names nothing.** An extension states where it belongs from what it does — a fog conceals, so it
-is late; a debug overlay must not be concealed, so it is later still — and needs no import of, or
-reference to, whatever else is on the phase. That is deliberately less precise than a dependency
-would be: it cannot say "immediately after that one", and there is no cycle to report because there
-is no graph. An effect that genuinely needs one particular extension's result should read a record
-that extension published, which is a real dependency rather than a positional one.
-
-### What keeps your work alive
-
-The graph elides work whose output nothing consumes, and that applies to an extension exactly as it
-does to a built-in pass. Thread a result into a record and it is consumed. Write something imported —
-the canvas, an imported texture — and it is a side effect. Want work that runs regardless and
-`make_side_effect()` on the pass builder says so.
-
-**An extension whose whole recording is elided is a correct, cheaper frame, not a failure**, and
-nothing reports it as one. It is a grey cluster with your extension's name on it in a graph dump.
-
-### The rest of `FrameContext`
-
-| | |
-|---|---|
-| `frame.graph` | the frame's `FrameGraph`. Record into it with the `graph_*` helpers, exactly as the built-in passes do |
-| `frame.view` | the `GPUViewContext` — camera, uniforms, frame index |
-| `frame.phase` | which phase this is |
-| `frame.resolution` | `[width, height]` of what you are drawing into, from the live handle |
-| `frame.describe(handle)` | the descriptor of any resource, for a pass that has to relate two of them |
-| `frame.is_open` | records are per-frame. A record held past the end of the frame is a retained handle by another name, and both reading and publishing through one say so |
-
-### Not built yet
-
-Two pieces of the extension design are named in `RENDER_EXTENSION_DESIGN.md` and **do not exist**:
-`RenderExtensionRegistry.describe()` (printing the pipeline as data) and `FrameProduct` (opting into
-optional frame products such as velocity or a readable copy of the colour). Do not write against
-them.
-
----
-
-## 7. Rendering somewhere other than the canvas
-
-```js
-import { GPUTextureContext } from "./renderer/texture/GPUTextureContext.js";
-
-renderer.render_to_target(camera, scene, dt, GPUTextureContext.fromTexture(texture, renderer.device));
-```
-
-`render()` *is* this call with the canvas's current texture as the target — the canvas is one target
-among others, not a privileged one.
-
-**The target says where the picture goes, not how big it is.** Everything the frame is built out of —
-the G-buffer, the visibility buffer, the depth ping-pong, the temporal history — is sized from
-`renderer.output_resolution`, so **the target must be that size**. A caller wanting a different one
-calls `renderer.resize()` first and puts the size back afterwards.
-
-This is what makes a frame readable at all: a canvas texture is configured by the presentation path
-and cannot carry `COPY_SRC`; a texture you own can. Thumbnails, asset previews and image-based tests
-all go through here.
-
----
-
-## 8. Content whose vertices change — the dynamic-mesh path
-
-A trail behind a projectile, a ribbon, a tube along a path, a batch of CPU-simulated particles, a
-debug line: content rewritten every frame cannot pay for a meshlet build, and rebuilding meshlets per
-frame to force it down the standard path is explicitly not the answer.
-
-```js
-const mesh = DynamicMesh.from(geometry, [1, 0.5, 0, 1]);   // Geometry, not MeshletGeometry
-
-batch.add(mesh);          // DynamicMeshBatch, yours — not the Scene's
-mesh.visible = false;     // hide without leaving the batch
-geometry.needsUpdate = true;   // you say when the vertices changed; nothing watches the arrays
-```
-
-This is **a separate path, not a variant of the standard one.** A `DynamicMesh` holds a plain
-`Geometry` and its own `transform`, is no entity of the scene, gets no row in the scene database,
-and is drawn by a pipeline of its own after the standard geometry path has finished with the frame.
-
-Drawing it over the scene is a `GPUDynamicMeshRenderer` inside an extension of yours (§6); drawing it
-inside the transparency pipeline is a `DynamicMeshAVBOITChannel` (below). Two things to know either
-way:
-
-**There is one vertex layout and it is fixed** — 8 floats: position at `[0..2]`, one reserved slot at
-`[3]`, RGBA colour at `[4..7]`. A dynamic mesh is drawn by a single pipeline, so letting each geometry
-declare its own attribute set would buy nothing and cost either a pipeline per layout or a shader
-that branches per vertex. Your geometry needs a position attribute and an index; a colour attribute is
-optional and is multiplied by the mesh's flat `color`.
-
-**`GPUDynamicMeshRenderer.opaque` chooses blending or depth**, and it is a property of the pass
-rather than of a mesh — the whole batch moves together. Left `false` the content is blended and only depth-tests,
-which is what effects want. Set it and the pass writes depth instead: a solid surface with no meshlet
-build behind it has no depth ordering otherwise, and no CPU sort can give it one, because a painter's
-order over triangles is wrong wherever two of them interpenetrate.
-
-`graph_draw` hands back `{ color, depth }`, and an extension publishes both, as in §6. The depth is a
-new handle when the pass wrote it. Anything reading the scene depth after you — depth of field,
-motion blur, the NSS upscaler, the next extension — has to be given that handle; a development build
-refuses the frame when it is not. Left `false`, the depth comes back as it went in.
-
-That is also what decides the phase for solid content. At `AfterLighting` transparency has not run
-yet, and it tests against the depth you published, so glass in front of the batch covers it. At
-`AfterTransparency` the glass is already resolved into the colour, and the batch is drawn over it.
-
-Residency is keyed on **the geometry**, not on batch membership, so a mesh that blinks off for a
-frame or is removed and re-added keeps its buffers.
-
-### Inside the transparency pipeline instead of over it
-
-Blended content drawn by an extension composites over transparency that is already resolved: a trail
-behind a pane of glass is drawn on top of the glass. A batch that has to interleave with transparent
-surfaces by depth is registered as a **transparency channel** instead:
-
-```js
-const channel = new DynamicMeshAVBOITChannel(batch);
-
-renderer.add_transparency_channel(channel);
-// ...
-renderer.remove_transparency_channel(channel);
-channel.destroy();                 // the channel owns the batch's GPU buffers
-channel.release(geometry);         // ... and, like the renderer, frees a geometry gone for good
-```
-
-The channel is an `AVBOITSideChannel`, the contract the GPU particles already implement: its
-fragments go into the same extinction volume and accumulators as the transparent meshes and the
-particles, so all three occlude each other order-independently, within AVBOIT's own limits (two
-surfaces in one depth slice blend rather than sort). What is drawn is straight alpha, unlit, fogged
-by the volumetrics at its depth, depth-tested against the opaque scene and never written. A mesh is
-drawn when it is visible, has positive flat alpha and has a triangle with a vertex of positive alpha;
-a batch with none says so, and costs the frame nothing. **Under `ShadeTransparencyMode.MBOIT`, or
-with transparency off, a channel is not drawn at all** — as the particles are not.
-
-What that costs and changes: a channel with something live makes the transparency pipeline run for
-the frame even when nothing else is transparent; its depth range shares the pipeline's 128 slices with
-every transparent surface on screen (off-screen meshes mark none); and what extensions draw at
-`AfterTransparency` — path display, the selection highlight — lands over it, since it is resolved
-before that phase. Registering the same channel twice keeps one.
-
-From the ECS side the same registration goes through `GraphicsEngine.add_transparency_channel`, which
-holds channels across a restart the way `add_extension` holds extensions. `Trail3DSystem` draws
-trails this way.
-
----
-
-## 9. Frame-level switches
-
-| | |
-|---|---|
-| `feature_shadows_enabled` | |
-| `feature_taa_enabled` | when off, there is no upscale and the phases either side of it are the same size |
-| `transparency_mode` | `ShadeTransparencyMode.AVBOIT` (default) or `.MBOIT`; both run at the one transparency call site with the same inputs, safe to flip per frame — except that side channels (the GPU particles, transparency channels such as trails) are drawn under AVBOIT only |
-| `avboit` | `AVBOITSettings`: `transmission_tint_from_base_color` (default off) filters transmitted light by base colour per channel under AVBOIT — off, a flip of `transparency_mode` changes no material's meaning |
-| `internal_resolution_scale` | render internally below output resolution; `DynamicResolutionScaling` drives it from frame time |
-| `pixel_ratio`, `output_resolution`, `aspect_ratio`, `resize(x, y)` | |
-| `motion_blur`, `dof`, `dof_unreal`, `nss`, `restir_di`, `path_tracer` | sub-objects with their own settings |
-| `frame_count` | |
-| `profile_session` | assign a `GPUProfileSession` to record GPU timings; null when nothing is profiling |
-
----
-
-## 10. Where things live
-
-```
-shade/renderer/
-├── Renderer.js               the whole surface in §2, §7, §9
-├── scene/                    Scene, GPUSceneContext, rows/ — GPUSceneRows, place_primitive; DynamicMesh
-├── geometry/                 Geometry, MeshletGeometry, the builders, primitives/
-├── material/                 ShadeMaterial, StandardShadeMaterial
-├── texture/                  ShadeTexture, GPUTextureContext, source/ShadeImage
-├── light/                    LightCollection, make_sunlight, model/{Light,DirectionalLight,PointLight,SpotLight}
-├── camera/                   PerspectiveCamera
-├── loader/gltf/              load_gltf, SceneBundle
-├── extension/                RenderExtension, FrameContext, FrameRecord, the four records
-├── dynamic/                  GPUDynamicMeshRenderer, DynamicMeshAVBOITChannel, and their one vertex layout
-└── animation/                GPUAnimationManager — skins and clips
-```
-
-`prefab_compile` and `prefab_place` live with the ECS, in `engine/graphics3/prefab/`, because a
-placement is entities.
-
-`shade/device/mock/` holds a **validating software device**: no shader execution, but real validation
-of bindings, passes, resources and texture copies. It is how the renderer's own tests run without a
-GPU, and it is available to yours. Specs must never acquire a real device — see `vitest.config.mjs`,
-which explains at length why.