@woosh/meep-engine 3.30.0 → 3.31.0

package/src/shade/RENDERER_CONTRACT.md

@@ -386,8 +386,8 @@ import { FramePhase } from "./renderer/extension/FramePhase.js";
 import { SceneColor } from "./renderer/extension/SceneColor.js";
 import { ViewTextures } from "./renderer/extension/ViewTextures.js";
 
-class TrailExtension extends RenderExtension {
-    name = "trails";
+class PathExtension extends RenderExtension {
+    name = "path display";
 
     phase = FramePhase.AfterTransparency;
 
@@ -409,13 +409,18 @@ class TrailExtension extends RenderExtension {
     }
 }
 
-const registered = renderer.add_extension(new TrailExtension());
+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
@@ -569,7 +574,9 @@ This is **a separate path, not a variant of the standard one.** A `DynamicMesh`
 `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 is a `GPUDynamicMeshRenderer` inside an extension of yours (§6). Two things to know:
+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
@@ -586,6 +593,41 @@ order over triangles is wrong wherever two of them interpenetrate.
 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
@@ -594,7 +636,7 @@ frame or is removed and re-added keeps its buffers.
 |---|---|
 | `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 |
+| `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)` | |
@@ -617,7 +659,7 @@ shade/renderer/
 ├── camera/                   PerspectiveCamera
 ├── loader/gltf/              load_gltf, SceneBundle
 ├── extension/                RenderExtension, FrameContext, FrameRecord, the four records
-├── dynamic/                  GPUDynamicMeshRenderer and its one vertex layout
+├── dynamic/                  GPUDynamicMeshRenderer, DynamicMeshAVBOITChannel, and their one vertex layout
 └── animation/                GPUAnimationManager — skins and clips
 ```
 

package/src/shade/descriptor/texture/format/gpu_texture_formats_copy_compatible.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Whether WebGPU lets a texture of one format be copied into a texture of the other.
+ *
+ * `copyTextureToTexture` asks for the two to be "copy-compatible", which is looser than equal:
+ * "format1 equals format2, or format1 and format2 differ only in whether they are srgb formats (have
+ * the -srgb suffix)". The two halves of an sRGB pair store the same bytes in the same layout and
+ * differ only in how a sample decodes them, and a copy samples nothing — so the pair may be copied
+ * either way round, and every byte arrives as it was stored.
+ *
+ * **Compatible is not the same as meaning the same.** Because nothing is decoded on the way, an
+ * sRGB-encoded albedo copied into `rgba8unorm` is sampled there as its encoded values, not as the
+ * colours it held. This answers whether the device accepts the copy. A caller that needs the colours
+ * to survive, not only the bytes, needs equal formats instead, which is what
+ * {@link GPUResidentMaterialContext} asks for before it copies into its atlas.
+ *
+ * @param {GPUTextureFormat} a
+ * @param {GPUTextureFormat} b
+ * @returns {boolean} symmetric, and true for any format and itself, whether or not it has an sRGB twin
+ * @throws {Error} for a name that is not a GPUTextureFormat, which is compatible with nothing a device
+ *         could hold
+ */
+export function gpu_texture_formats_copy_compatible(a: GPUTextureFormat, b: GPUTextureFormat): boolean;
+//# sourceMappingURL=gpu_texture_formats_copy_compatible.d.ts.map

package/src/shade/descriptor/texture/format/gpu_texture_formats_copy_compatible.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu_texture_formats_copy_compatible.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/descriptor/texture/format/gpu_texture_formats_copy_compatible.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,+FAJa,OAAO,CAQnB"}

package/src/shade/descriptor/texture/format/gpu_texture_formats_copy_compatible.js

@@ -0,0 +1,28 @@
+import { gpu_texture_format_srgb } from "./gpu_texture_format_srgb.js";
+
+/**
+ * Whether WebGPU lets a texture of one format be copied into a texture of the other.
+ *
+ * `copyTextureToTexture` asks for the two to be "copy-compatible", which is looser than equal:
+ * "format1 equals format2, or format1 and format2 differ only in whether they are srgb formats (have
+ * the -srgb suffix)". The two halves of an sRGB pair store the same bytes in the same layout and
+ * differ only in how a sample decodes them, and a copy samples nothing — so the pair may be copied
+ * either way round, and every byte arrives as it was stored.
+ *
+ * **Compatible is not the same as meaning the same.** Because nothing is decoded on the way, an
+ * sRGB-encoded albedo copied into `rgba8unorm` is sampled there as its encoded values, not as the
+ * colours it held. This answers whether the device accepts the copy. A caller that needs the colours
+ * to survive, not only the bytes, needs equal formats instead, which is what
+ * {@link GPUResidentMaterialContext} asks for before it copies into its atlas.
+ *
+ * @param {GPUTextureFormat} a
+ * @param {GPUTextureFormat} b
+ * @returns {boolean} symmetric, and true for any format and itself, whether or not it has an sRGB twin
+ * @throws {Error} for a name that is not a GPUTextureFormat, which is compatible with nothing a device
+ *         could hold
+ */
+export function gpu_texture_formats_copy_compatible(a, b) {
+    // each side is taken to its sRGB spelling where it has one, so the two halves of a pair meet on
+    // the same name, and a format with no twin is compared as given
+    return (gpu_texture_format_srgb(a) ?? a) === (gpu_texture_format_srgb(b) ?? b);
+}

package/src/shade/descriptor/texture/format/gpu_texture_formats_view_compatible.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Whether WebGPU lets a texture of one format be viewed as the other, which is what `createTexture`
+ * asks of every entry of its `viewFormats`.
+ *
+ * The two must be "texture view format compatible on a given device": "format equals viewFormat, or
+ * format and viewFormat differ only in whether they are srgb formats (have the -srgb suffix) and
+ * device.[[features]] contains "core-features-and-limits"". Short of that last clause, this is the
+ * copy rule word for word, so the pairs are asked of {@link gpu_texture_formats_copy_compatible}.
+ * The device is where WebGPU keeps the two rules apart: the copy rule has no such clause, so a
+ * compatibility-mode device may copy `rgba8unorm-srgb` into `rgba8unorm` but may view a texture only
+ * as its own format.
+ *
+ * Viewing across the pair changes how a sample decodes the bytes and nothing else. That is why
+ * {@link texture_encode} binds an sRGB source through a view in its linear twin: it wants the bytes as
+ * stored, not decoded.
+ *
+ * @param {GPUTextureFormat} format the texture's
+ * @param {GPUTextureFormat} view_format one entry of its `viewFormats`
+ * @param {GPUSupportedFeatures} features those of the device the texture is made on
+ * @returns {boolean} symmetric in the two formats, and true for any format and itself on any device
+ * @throws {Error} for a name that is not a GPUTextureFormat, which is compatible with nothing a device
+ *         could hold
+ */
+export function gpu_texture_formats_view_compatible(format: GPUTextureFormat, view_format: GPUTextureFormat, features: GPUSupportedFeatures): boolean;
+//# sourceMappingURL=gpu_texture_formats_view_compatible.d.ts.map

package/src/shade/descriptor/texture/format/gpu_texture_formats_view_compatible.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu_texture_formats_view_compatible.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/descriptor/texture/format/gpu_texture_formats_view_compatible.js"],"names":[],"mappings":"AASA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,8IAJa,OAAO,CAanB"}

package/src/shade/descriptor/texture/format/gpu_texture_formats_view_compatible.js

@@ -0,0 +1,42 @@
+import { gpu_texture_formats_copy_compatible } from "./gpu_texture_formats_copy_compatible.js";
+
+/**
+ * Present on every core device, and missing only from a compatibility-mode one.
+ *
+ * @type {GPUFeatureName}
+ */
+const CORE_FEATURE = "core-features-and-limits";
+
+/**
+ * Whether WebGPU lets a texture of one format be viewed as the other, which is what `createTexture`
+ * asks of every entry of its `viewFormats`.
+ *
+ * The two must be "texture view format compatible on a given device": "format equals viewFormat, or
+ * format and viewFormat differ only in whether they are srgb formats (have the -srgb suffix) and
+ * device.[[features]] contains "core-features-and-limits"". Short of that last clause, this is the
+ * copy rule word for word, so the pairs are asked of {@link gpu_texture_formats_copy_compatible}.
+ * The device is where WebGPU keeps the two rules apart: the copy rule has no such clause, so a
+ * compatibility-mode device may copy `rgba8unorm-srgb` into `rgba8unorm` but may view a texture only
+ * as its own format.
+ *
+ * Viewing across the pair changes how a sample decodes the bytes and nothing else. That is why
+ * {@link texture_encode} binds an sRGB source through a view in its linear twin: it wants the bytes as
+ * stored, not decoded.
+ *
+ * @param {GPUTextureFormat} format the texture's
+ * @param {GPUTextureFormat} view_format one entry of its `viewFormats`
+ * @param {GPUSupportedFeatures} features those of the device the texture is made on
+ * @returns {boolean} symmetric in the two formats, and true for any format and itself on any device
+ * @throws {Error} for a name that is not a GPUTextureFormat, which is compatible with nothing a device
+ *         could hold
+ */
+export function gpu_texture_formats_view_compatible(format, view_format, features) {
+    // the copy rule's pairs, the format itself or its twin across -srgb; asking it also throws for a
+    // name that is not a format
+    if (!gpu_texture_formats_copy_compatible(format, view_format)) {
+        return false;
+    }
+
+    // the twin, as opposed to the format itself, only on a core device
+    return format === view_format || features.has(CORE_FEATURE);
+}

package/src/shade/device/ShadeGPUCommandContext.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ShadeGPUCommandContext.d.ts","sourceRoot":"","sources":["../../../../src/shade/device/ShadeGPUCommandContext.js"],"names":[],"mappings":"AA8CA;;;;;;GAMG;AACH;IAoLI;;;;;OAKG;IACH,wBAJW,eAAe,UACf,MAAM,GACJ,sBAAsB,CA6BlC;IAjND;;;;OAIG;IACH,iBAEC;IAED;;;OAGG;IACH,mCAEC;IASD;;;;OAIG;IACH,qCAEC;IAED;;;;;OAKG;IACH,yEAEC;IAED;;;;;;OAMG;IACH,wBAEC;IAeD;;;;;;;;OAQG;IACH,wCAIC;IAED;;;;;;OAMG;IACH,2BAJW,gBAAgB,gBAChB,MAAM,GACJ,IAAI,CAOhB;IAOD;;;OAGG;IACH,wBAEC;IAED;;;OAGG;IACH,+EAEC;IAqBD;;;OAGG;IACH,yBAA0B;IAE1B;;;OAGG;IACH,6BAA8B;IAE9B;;;OAGG;IACH,0BAcC;IA6CD;;;OAGG;IACH,2BAFa,wBAAwB,CAIpC;IAED;;;OAGG;IACH,mBAFW,UAAU,QAapB;IAED;;;;;OAKG;IACH,wCAHW,MAAM,SACN,MAAM,QAWhB;IAED;;;;OAIG;IACH,qBAEC;IAED;;;;;;;;;OASG;IACH,oDALW,MAAM,6CAEN,MAAM,SACN,MAAM,QAqChB;IAGD;;;;;OAKG;IACH,uHAKC;IAED;;;;;;OAMG;IACH,qHAMC;IAED;;;;OAIG;IACH,yDAFa,0BAA0B,CAatC;IAGD;;;;;;;;;OASG;IACH;QAP8C,QAAQ,EAA3C,yBAAyB;QACR,KAAK,GAAtB,MAAM;QAC2B,QAAQ,GAAzC,oBAAoB,EAAE;QACyC,SAAS,GAAxE;YAAC,MAAM,EAAE,YAAY,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAC;QAElD,0BAA0B,CAgCtC;IAED;;;;OAIG;IACH,sBAFW,MAAM,QAOhB;IAED;;;OAGG;IACH,sBAIC;IAED;;;;OAIG;IACH,yBAFW,MAAM,QAKhB;IAED;;;;;;;;;;;OAWG;IACH;QAT4B,KAAK,GAAtB,MAAM;QAC4B,QAAQ,EAA1C,wBAAwB;QACS,QAAQ,GAAzC,oBAAoB,EAAE;QACkB,gBAAgB,EAAxD,8BAA8B;QACgB,sBAAsB;QACL,SAAS,GAAxE;YAAC,MAAM,EAAE,YAAY,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAC;QAElD,yBAAyB,CAuCrC;IAED;;;;OAIG;IACH,sDAFa,yBAAyB,CAarC;IAED;;;;;;;OAOG;IACH,mDALW,MAAM,cACN,MAAM,6CAEN,MAAM,QAIhB;IAED;;;;;;OAMG;IACH,2CAFY,OAAO,CAYlB;IAUD;;;;;;OAMG;IACH,+BAJW,MAAM,iBAAe,QACrB,MAAM,aAuBhB;IAED;;;;;;;OAOG;IACH,qCANW,WAAW,UACX,MAAM,iBAAe,WACrB,MAAM,SACN,MAAM,aAwBhB;IAeD;;;;;;;;;OASG;IACH,0BAJW,2BAA2B,aAEzB;QAAC,MAAM,EAAE,YAAY,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,GAAC,SAAS,CA2B1E;IAED;;;;;;OAMG;IACH,sCALW,UAAU,oBAEV,MAAM,iBAAe,aAgB/B;IAED;;;;;;OAMG;IACH,wDAJW,MAAM,QACN,UAAU,oBAsBpB;IAED;;;;;;;OAOG;IACH,8CALW,MAAM,QACN,WAAW,eACX,MAAM,QACN,MAAM,QAuBhB;IA0BD;;OAEG;IACH,eA0CC;;CACJ;uCAz0BY,OAAO,2DAA2D,EAAE,wBAAwB;yBAI5F,OAAO,wDAAwD,EAAE,UAAU;wCAC3E,OAAO,6DAA6D,EAAE,yBAAyB;8BAC/F,OAAO,gCAAgC,EAAE,eAAe;0CACxD,OAAO,4DAA4D,EAAE,2BAA2B;yBAChG,OAAO,uCAAuC,EAAE,UAAU;6BAC1D,OAAO,uCAAuC,EAAE,cAAc;+BAC9D,OAAO,sCAAsC,EAAE,gBAAgB;yCAbnC,qCAAqC;2CANnC,sCAAsC;6BANpD,mCAAmC;0CAOtB,qCAAqC"}
+{"version":3,"file":"ShadeGPUCommandContext.d.ts","sourceRoot":"","sources":["../../../../src/shade/device/ShadeGPUCommandContext.js"],"names":[],"mappings":"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"}