@woosh/meep-engine 3.30.0 → 3.32.0

package/src/shade/renderer/dynamic/shader_dynamic_mesh_avboit_splat.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Bind group of the warp, set once per pass. Group 0 is the dynamic-mesh group, per mesh.
+ * @type {number}
+ */
+export const DYNAMIC_MESH_AVBOIT_SPLAT_BIND_GROUP_PASS: number;
+/**
+ * Bind group of the volume atomics.
+ * @type {number}
+ */
+export const DYNAMIC_MESH_AVBOIT_SPLAT_BIND_GROUP_VOLUME: number;
+/**
+ * Samples per pixel of the splat's raster, which is what a fragment's extinction is weighted by the
+ * share of. Four, being the only count above one that WebGPU guarantees.
+ * @type {number}
+ */
+export const DYNAMIC_MESH_AVBOIT_SPLAT_SAMPLES: number;
+/**
+ * The splat pipeline: no depth, one never-written attachment to size the raster, multisampled so a
+ * fragment knows how much of its voxel it covers, both faces — a trail is seen from inside and out.
+ * The attachment is the splat's own ({@link DYNAMIC_MESH_AVBOIT_SPLAT_SAMPLES} samples), not the
+ * volume's single-sampled one the meshlet and particle splats share.
+ * @type {RenderPipelineDescriptor}
+ */
+export const DYNAMIC_MESH_AVBOIT_SPLAT_PIPELINE: RenderPipelineDescriptor;
+/** The splat shader's resource set, for building its pass-level bind groups. */
+export const DYNAMIC_MESH_AVBOIT_SPLAT_RESOURCES: ShaderResourceSetDescriptor;
+/** The assembled shader, for the validity tier. */
+export const shader_dynamic_mesh_avboit_splat: ShaderDescriptor;
+import { RenderPipelineDescriptor } from "../../descriptor/pipeline/render/RenderPipelineDescriptor.js";
+import { ShaderResourceSetDescriptor } from "../shader/resource/ShaderResourceSetDescriptor.js";
+import { ShaderDescriptor } from "../shader/ShaderDescriptor.js";
+//# sourceMappingURL=shader_dynamic_mesh_avboit_splat.d.ts.map

package/src/shade/renderer/dynamic/shader_dynamic_mesh_avboit_splat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_dynamic_mesh_avboit_splat.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/dynamic/shader_dynamic_mesh_avboit_splat.js"],"names":[],"mappings":"AAkBA;;;GAGG;AACH,wDAFU,MAAM,CAE2C;AAE3D;;;GAGG;AACH,0DAFU,MAAM,CAE6C;AAE7D;;;;GAIG;AACH,gDAFU,MAAM,CAEmC;AAuGnD;;;;;;GAMG;AACH,iDAFU,wBAAwB,CAa/B;AAEH,gFAAgF;AAChF,8EAA6D;AAE7D,mDAAmD;AACnD,gEAA2D;yCAjKlB,8DAA8D;4CAU3D,mDAAmD;iCAC9D,+BAA+B"}

package/src/shade/renderer/dynamic/shader_dynamic_mesh_avboit_splat.js

@@ -0,0 +1,163 @@
+import { PipelineLayoutDescriptor } from "../../descriptor/pipeline/PipelineLayoutDescriptor.js";
+import { RenderPipelineDescriptor } from "../../descriptor/pipeline/render/RenderPipelineDescriptor.js";
+import { AVBOIT_WARP_STRUCT } from "../rasterize/native/avboit/AVBOIT_WARP_STRUCT.js";
+import { chunk_avboit_coverage } from "../rasterize/native/avboit/chunk_avboit_coverage.js";
+import { chunk_avboit_splat_slice } from "../rasterize/native/avboit/chunk_avboit_splat_slice.js";
+import {
+    chunk_avboit_transmittance_to_extinction
+} from "../rasterize/native/avboit/chunk_avboit_transmittance_to_extinction.js";
+import { chunk_avboit_view_depth_to_physical } from "../rasterize/native/avboit/chunk_avboit_view_depth_to_physical.js";
+import { AVBOIT_SPLAT_DUMMY_FORMAT } from "../rasterize/native/avboit/shader_avboit_splat.js";
+import { CodeChunk } from "../shader/compiler/CodeChunk.js";
+import { ShaderResourceSetDescriptor } from "../shader/resource/ShaderResourceSetDescriptor.js";
+import { ShaderDescriptor } from "../shader/ShaderDescriptor.js";
+import { atomic_u32 } from "../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../shader/type/WebGPUArray.js";
+import { chunk_dynamic_mesh_avboit_vertex } from "./chunk_dynamic_mesh_avboit_vertex.js";
+import { DYNAMIC_MESH_RESOURCES } from "./shader_dynamic_mesh.js";
+
+/**
+ * Bind group of the warp, set once per pass. Group 0 is the dynamic-mesh group, per mesh.
+ * @type {number}
+ */
+export const DYNAMIC_MESH_AVBOIT_SPLAT_BIND_GROUP_PASS = 1;
+
+/**
+ * Bind group of the volume atomics.
+ * @type {number}
+ */
+export const DYNAMIC_MESH_AVBOIT_SPLAT_BIND_GROUP_VOLUME = 2;
+
+/**
+ * Samples per pixel of the splat's raster, which is what a fragment's extinction is weighted by the
+ * share of. Four, being the only count above one that WebGPU guarantees.
+ * @type {number}
+ */
+export const DYNAMIC_MESH_AVBOIT_SPLAT_SAMPLES = 4;
+
+/**
+ * The dynamic meshes' AVBOIT splat: every mesh's triangles rasterized at the volume's resolution,
+ * each fragment's extinction added into the voxel volume through `avboit_splat_slice` — the same
+ * write path as the meshlet and particle splats, so a trail, a particle and a surface at one depth
+ * pile up in one field.
+ *
+ * Coverage is the vertex colour's alpha times the mesh's, through `avboit_coverage` — the function
+ * the draw weights the same fragment by — and `T_self = 1 - coverage`, untinted. A fragment that
+ * has faded to nothing covers nothing and writes nothing, which on a trail is its whole aged-out
+ * tail.
+ *
+ * **Weighted by the share of the voxel the triangle covers.** A voxel is eight pixels across, and a
+ * trail is often narrower than that. Sampled at the voxel's centre alone, a thin trail either
+ * crosses the centre and writes its full extinction there or misses it and writes nothing, so its
+ * occlusion of what lies behind it came and went as it moved by a fraction of a voxel — beaded along
+ * a curve, flickering in motion. Here the raster has {@link DYNAMIC_MESH_AVBOIT_SPLAT_SAMPLES}
+ * samples per pixel, the fragment runs wherever any of them is covered, and its extinction is scaled
+ * by the covered fraction: the voxel gets the triangle's extinction averaged over its footprint, as
+ * a volume that coarse can hold it. The triangles of one mesh cover disjoint samples, so the
+ * fractions of the triangles sharing a voxel add up to at most one layer; a fully covered voxel is
+ * written exactly as before. What remains is the average's own bias — a trail a fraction of a voxel
+ * wide occludes what is behind it by that fraction of its extinction — which holds still as the
+ * trail moves.
+ *
+ * Depth is the fragment's own view depth from the shared vertex stage, through curve → warp →
+ * physical and the two-slice linear split the other splats make. No depth attachment, for the
+ * reason the meshlet splat has none: a splat behind an opaque surface lies deeper than anything the
+ * draw will look it up for.
+ *
+ * Group 0 is `DYNAMIC_MESH_RESOURCES`' own group, the same object, so a mesh's bindings are the ones
+ * its residency already builds for the pass over the scene.
+ */
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.addGroup(DYNAMIC_MESH_RESOURCES.groups[0]);
+
+resources.createGroup()
+    .addStorageBuffer("warp", AVBOIT_WARP_STRUCT);
+
+resources.createGroup()
+    .addStorageBuffer("extinction_volume", WebGPUArray.from(atomic_u32), true)
+    .addStorageBuffer("overflow_slice", WebGPUArray.from(atomic_u32), true);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@vertex
+fn vs_main(@builtin(vertex_index) vi : u32) -> DynamicMeshAVBOITVertexOut {
+    return dynamic_mesh_avboit_vertex(vi);
+}
+
+@fragment
+fn fs_main(in : DynamicMeshAVBOITVertexOut, @builtin(sample_mask) sample_mask : u32) {
+    // the coverage the draw weights this fragment by, through the same function
+    let coverage = avboit_coverage(in.color.a);
+
+    if (coverage <= 0.0) {
+        // faded out: occludes nothing
+        return;
+    }
+
+    // the share of the voxel's samples this triangle covers
+    let footprint = f32(countOneBits(sample_mask)) / ${DYNAMIC_MESH_AVBOIT_SPLAT_SAMPLES}.0;
+
+    let extinction = avboit_transmittance_to_extinction(vec3<f32>(1.0 - coverage)) * footprint;
+
+    let p = avboit_view_depth_to_physical(&warp, in.view_depth);
+
+    // in.clip is @builtin(position): .xy the low-resolution pixel
+    let texel = vec2<u32>(in.clip.xy);
+    let column = (texel.y * warp.voxel_width + texel.x) * warp.physical_count;
+
+    // linear splat between the two slices around the fragment
+    let c = p - 0.5;
+    let slice = i32(floor(c));
+    let fraction = c - floor(c);
+
+    avboit_splat_slice(column, slice, extinction * (1.0 - fraction), texel);
+    avboit_splat_slice(column, slice + 1, extinction * fraction, texel);
+}
+`, [
+    chunk_dynamic_mesh_avboit_vertex,
+    chunk_avboit_coverage,
+    chunk_avboit_transmittance_to_extinction,
+    chunk_avboit_view_depth_to_physical,
+    chunk_avboit_splat_slice,
+]);
+
+const descriptor = ShaderDescriptor.from({ label: "Dynamic Mesh AVBOIT Splat", body, resources });
+
+// Built group by group: the atomics are fragment-only, and WebGPU refuses a read-write storage
+// buffer that is visible to the vertex stage. The dynamic-mesh group keeps the visibility it has in
+// the pass over the scene, so the two layouts agree.
+const groups = resources.groups;
+const layout = PipelineLayoutDescriptor.from([
+    groups[0].generateBindGroupLayoutDescriptor(GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT),
+    groups[DYNAMIC_MESH_AVBOIT_SPLAT_BIND_GROUP_PASS].generateBindGroupLayoutDescriptor(GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT),
+    groups[DYNAMIC_MESH_AVBOIT_SPLAT_BIND_GROUP_VOLUME].generateBindGroupLayoutDescriptor(GPUShaderStage.FRAGMENT),
+], resources.immediateSize);
+
+/**
+ * The splat pipeline: no depth, one never-written attachment to size the raster, multisampled so a
+ * fragment knows how much of its voxel it covers, both faces — a trail is seen from inside and out.
+ * The attachment is the splat's own ({@link DYNAMIC_MESH_AVBOIT_SPLAT_SAMPLES} samples), not the
+ * volume's single-sampled one the meshlet and particle splats share.
+ * @type {RenderPipelineDescriptor}
+ */
+export const DYNAMIC_MESH_AVBOIT_SPLAT_PIPELINE = RenderPipelineDescriptor.from({
+    label: "Dynamic Mesh AVBOIT Splat",
+    layout,
+    vertex: { module: { code: descriptor.source }, entryPoint: "vs_main" },
+    fragment: {
+        module: { code: descriptor.source },
+        entryPoint: "fs_main",
+        targets: [{ format: AVBOIT_SPLAT_DUMMY_FORMAT, writeMask: 0 }],
+    },
+    primitive: { topology: "triangle-list", cullMode: "none" },
+    multisample: { count: DYNAMIC_MESH_AVBOIT_SPLAT_SAMPLES },
+});
+
+/** The splat shader's resource set, for building its pass-level bind groups. */
+export const DYNAMIC_MESH_AVBOIT_SPLAT_RESOURCES = resources;
+
+/** The assembled shader, for the validity tier. */
+export const shader_dynamic_mesh_avboit_splat = descriptor;

package/src/shade/renderer/extension/RENDER_EXTENSION_DESIGN.md

@@ -29,6 +29,15 @@ and that is the trade — it cannot say "immediately after that one", and there
 because there is no graph. §1.4, §3.1, §3.6, §5, §7, §8 and §11 are updated; §3.6's ambiguity check
 was never built and is unaffected.
 
+**Revised 2026-09-24: trails left the `AfterTransparency` chain.** §9's first known limit — an
+extension cannot take part in OIT — still holds for extensions, and it is why trails moved out: a
+trail drawn at `AfterTransparency` covered every transparent surface whatever its depth. They are now
+a *transparency channel* (`Renderer.add_transparency_channel`, `GraphicsEngine.add_transparency_channel`),
+drawn inside the AVBOIT pipeline beside the particles; see the AVBOIT ledger, entries 22 and 23. The
+chain in §8's table is five deep, and the fog still covers trails, by construction: it runs after the
+transparency resolve they are part of. So does the rest of the chain, which is the one visible
+reordering — path display and the highlight, which trails used to draw over, now draw over trails.
+
 ---
 
 ## 0. Summary
@@ -715,7 +724,7 @@ value becomes a publication.
 | `PathDisplaySystem` | `AfterTransparency` | — |
 | `HighlightSystem` | `AfterTransparency` | reads `ViewTextures.visibility_*`, unchanged in meaning |
 | `DebugDrawSystem` | `AfterTransparency` | `relative_order = 2` |
-| `Trail3DSystem` | `AfterTransparency` | — |
+| `Trail3DSystem` | ~~`AfterTransparency`~~ | *since 2026-09-24 a transparency channel, not an extension — see the revision note at the top* |
 | `probeShadePassInjection` | all | the gate is rewritten and gains the two checks it is currently blind to: a G-buffer replacement, and an order flip |
 
 **The `AfterTransparency` chain is settled, not open.** Fog of war is after the content
@@ -746,7 +755,9 @@ built-in post passes.
 
 **Extensions cannot participate in OIT.** Work at `AfterTransparency` composites over the resolved
 transparency; it cannot interleave with sorted transparents. True today, unchanged, and the honest
-reason the phase model has a ceiling.
+reason the phase model has a ceiling. *2026-09-24:* the ceiling is on extensions, not on callers —
+content that has to interleave registers a transparency channel (`AVBOITSideChannel`) instead, which
+is asked for its contribution inside the AVBOIT pipeline; trails do.
 
 **Extensions cannot add to a built-in pass** — no extra material variants in the G-buffer raster, no
 extra lights. A new pass is the only unit.

package/src/shade/renderer/fow/GPUFogOfWarRenderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUFogOfWarRenderer.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/fow/GPUFogOfWarRenderer.js"],"names":[],"mappings":"AAMA;;;;;;;;;GASG;AACH;IAmBI;;;;;;;OAOG;IACH,gBAQC;IAED;;;;;;;;;;;OAWG;IACH;QAR4B,KAAK;QACT,KAAK,EAAlB,MAAM;QACO,KAAK,EAAlB,MAAM;QAEyB,MAAM,EAArC,0BAAwB;QACT,KAAK;QAClB,MAAM,CAgBlB;;CAsGJ"}
+{"version":3,"file":"GPUFogOfWarRenderer.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/fow/GPUFogOfWarRenderer.js"],"names":[],"mappings":"AAMA;;;;;;;;;GASG;AACH;IAmBI;;;;;;;OAOG;IACH,gBAQC;IAED;;;;;;;;;;;OAWG;IACH;QAR4B,KAAK;QACT,KAAK,EAAlB,MAAM;QACO,KAAK,EAAlB,MAAM;QAEyB,MAAM,EAArC,0BAAwB;QACT,KAAK;QAClB,MAAM,CAgBlB;;CA6FJ"}

package/src/shade/renderer/fow/GPUFogOfWarRenderer.js

@@ -1,5 +1,5 @@
 import { assert } from "../../../core/assert.js";
-import { TextureDescriptor } from "../../descriptor/texture/TextureDescriptor.js";
+import { fow_obtain_mask } from "./fow_obtain_mask.js";
 import { TextureViewDescriptor } from "../../descriptor/texture/TextureViewDescriptor.js";
 import { SAMPLER_LINEAR_UPSCALE } from "../texture/SAMPLER_LINEAR_UPSCALE.js";
 import { shader_fog_of_war } from "./shader_fog_of_war.js";
@@ -143,20 +143,11 @@ export class GPUFogOfWarRenderer {
 
         const existing = this.#mask;
 
-        if (existing === null || existing.descriptor.size[0] !== width || existing.descriptor.size[1] !== height) {
-            /*
-             `r8unorm` because the mask is one byte per cell and is read through a linear sampler:
-             it has to be a filterable format, and a single-byte one keeps the upload as small as
-             the field itself.
-            */
-            this.#mask = graphics.textures.contextFromDescriptor(TextureDescriptor.from({
-                label: "fog of war mask",
-                size: [width, height],
-                format: "r8unorm",
-                mipLevelCount: 1,
-                usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST
-            }));
+        // fow_obtain_mask destroys the one it replaces — nothing else would, and overwriting the
+        // field used to leak it for the life of the process on every resolution change
+        this.#mask = fow_obtain_mask(graphics, existing, width, height);
 
+        if (this.#mask !== existing) {
             this.#mask_source = null;
             this.#mask_version = -1;
         }

package/src/shade/renderer/fow/fow_obtain_mask.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The mask texture for a fog field of this size, reusing the one already held when it fits.
+ *
+ * **The one it replaces is destroyed.** `TextureManager.contextFromDescriptor` is a plain factory —
+ * a `GPUTextureContext` with the descriptor attached, not cached and not owned by the manager — so
+ * nothing else will ever free it, and overwriting the field leaked it outright. The renderer owns
+ * the mask precisely to avoid that, and its `destroy()` only ever freed the current one: every
+ * resolution change of the field left the previous mask resident for the life of the process.
+ *
+ * @param {import("../GraphicsContext.js").GraphicsContext} graphics
+ * @param {GPUTextureContext|null} previous the mask currently held, if any
+ * @param {number} width in cells
+ * @param {number} height in cells
+ * @returns {GPUTextureContext} `previous` when it already fits, otherwise a new one
+ */
+export function fow_obtain_mask(graphics: import("../GraphicsContext.js").GraphicsContext, previous: GPUTextureContext | null, width: number, height: number): GPUTextureContext;
+//# sourceMappingURL=fow_obtain_mask.d.ts.map

package/src/shade/renderer/fow/fow_obtain_mask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fow_obtain_mask.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/fow/fow_obtain_mask.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,0CANW,OAAO,uBAAuB,EAAE,eAAe,YAC/C,oBAAkB,IAAI,SACtB,MAAM,UACN,MAAM,qBA0BhB"}

package/src/shade/renderer/fow/fow_obtain_mask.js

@@ -0,0 +1,41 @@
+import { TextureDescriptor } from "../../descriptor/texture/TextureDescriptor.js";
+
+/**
+ * The mask texture for a fog field of this size, reusing the one already held when it fits.
+ *
+ * **The one it replaces is destroyed.** `TextureManager.contextFromDescriptor` is a plain factory —
+ * a `GPUTextureContext` with the descriptor attached, not cached and not owned by the manager — so
+ * nothing else will ever free it, and overwriting the field leaked it outright. The renderer owns
+ * the mask precisely to avoid that, and its `destroy()` only ever freed the current one: every
+ * resolution change of the field left the previous mask resident for the life of the process.
+ *
+ * @param {import("../GraphicsContext.js").GraphicsContext} graphics
+ * @param {GPUTextureContext|null} previous the mask currently held, if any
+ * @param {number} width in cells
+ * @param {number} height in cells
+ * @returns {GPUTextureContext} `previous` when it already fits, otherwise a new one
+ */
+export function fow_obtain_mask(graphics, previous, width, height) {
+    if (
+        previous !== null
+        && previous !== undefined
+        && previous.descriptor.size[0] === width
+        && previous.descriptor.size[1] === height
+    ) {
+        return previous;
+    }
+
+    previous?.destroy();
+
+    /*
+     `r8unorm` because the mask is one byte per cell and is read through a linear sampler: it has to
+     be a filterable format, and a single-byte one keeps the upload as small as the field itself.
+    */
+    return graphics.textures.contextFromDescriptor(TextureDescriptor.from({
+        label: "fog of war mask",
+        size: [width, height],
+        format: "r8unorm",
+        mipLevelCount: 1,
+        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST
+    }));
+}

package/src/shade/renderer/frame_jitter_applies.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Whether this frame's camera projection should carry the temporal jitter.
+ *
+ * Only when something is going to resolve it. The Halton sequence keeps advancing either way —
+ * the frame counter drives it, so re-enabling is phase-correct — but pushing the offset into the
+ * projection with nothing to average the samples back together shears the frame by a different
+ * sub-pixel amount on each of the sixteen steps and then repeats: every geometric edge crawls on
+ * a sixteen-frame cycle and the picture is never still. Turning TAA off is exactly what a caller
+ * does to get a stable image — an A/B capture, a golden-image test, path tracing with the
+ * temporal filter out of the way — and it used to be the one configuration in which they could
+ * not have one.
+ *
+ * NSS consumes the same sequence and is not gated by the TAA flag, so it keeps its jitter.
+ *
+ * @param {boolean} taa_enabled
+ * @param {ShadeUpscalerType|number} upscale_type
+ * @returns {boolean}
+ */
+export function frame_jitter_applies(taa_enabled: boolean, upscale_type: ShadeUpscalerType | number): boolean;
+import { ShadeUpscalerType } from "./ShadeUpscalerType.js";
+//# sourceMappingURL=frame_jitter_applies.d.ts.map

package/src/shade/renderer/frame_jitter_applies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame_jitter_applies.d.ts","sourceRoot":"","sources":["../../../../src/shade/renderer/frame_jitter_applies.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,kDAJW,OAAO,gBACP,iBAAiB,GAAC,MAAM,GACtB,OAAO,CAInB;kCAtBiC,wBAAwB"}

package/src/shade/renderer/frame_jitter_applies.js

@@ -0,0 +1,23 @@
+import { ShadeUpscalerType } from "./ShadeUpscalerType.js";
+
+/**
+ * Whether this frame's camera projection should carry the temporal jitter.
+ *
+ * Only when something is going to resolve it. The Halton sequence keeps advancing either way —
+ * the frame counter drives it, so re-enabling is phase-correct — but pushing the offset into the
+ * projection with nothing to average the samples back together shears the frame by a different
+ * sub-pixel amount on each of the sixteen steps and then repeats: every geometric edge crawls on
+ * a sixteen-frame cycle and the picture is never still. Turning TAA off is exactly what a caller
+ * does to get a stable image — an A/B capture, a golden-image test, path tracing with the
+ * temporal filter out of the way — and it used to be the one configuration in which they could
+ * not have one.
+ *
+ * NSS consumes the same sequence and is not gated by the TAA flag, so it keeps its jitter.
+ *
+ * @param {boolean} taa_enabled
+ * @param {ShadeUpscalerType|number} upscale_type
+ * @returns {boolean}
+ */
+export function frame_jitter_applies(taa_enabled, upscale_type) {
+    return taa_enabled || upscale_type === ShadeUpscalerType.NSS;
+}

package/src/shade/renderer/geometry/bvh/GPUGeometryBVHManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUGeometryBVHManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/bvh/GPUGeometryBVHManager.js"],"names":[],"mappings":"AAkBA;;;GAGG;AAEH;;;;;GAKG;AACH,gDAGG;AAEH;;;;;;;;;;;GAWG;AACH,sCAFU,MAAM,CAEyB;AAmCzC;;;;;;;;;;;;;;GAcG;AACH;IA0II;;;OAGG;IACH,+BAoDC;IA1LD;;;OAGG;IACH,iCAEC;IAOD;;;OAGG;IACH,6BAEC;IAuCD;;OAEG;IACH,gCAEC;IAOD;;OAEG;IACH,mCAEC;IA+BD;;OAEG;IACH,gCAEC;IA6ED;;;;OAIG;IACH,iCAEC;IAED,+BAoBC;IAED;;;;;;;;;OASG;IACH,wCAIC;IAED;;;;;;;;;;;;;;OAcG;IACH,cALW,MAAM,UACN,eAAe,GAEb,sBAAsB,CAalC;IA8DD;;;;;;;;;;;;OAYG;IACH,wBAHW,MAAM,GACJ;QAAC,gBAAgB,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAA;KAAC,GAAC,SAAS,CAqB3I;IAED;;;;;;OAMG;IACH,mBAHW,MAAM,GACJ,MAAM,GAAC,SAAS,CAU5B;IAED;;;;;;;;;OASG;IACH,0BAFW,WAAW,QAQrB;IAED;;;;;;;;;;;OAWG;IACH,cAHW,MAAM,GACJ,OAAO,CA8BnB;IA4LD;;;;;;;OAOG;IACH,eAOC;;CAgIJ;8BAh1BY,OAAO,uBAAuB,EAAE,eAAe;yBAC/C,OAAO,sDAAsD,EAAE,UAAU;6BAbzD,mCAAmC;uCASzB,6BAA6B"}
+{"version":3,"file":"GPUGeometryBVHManager.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/geometry/bvh/GPUGeometryBVHManager.js"],"names":[],"mappings":"AAkBA;;;GAGG;AAEH;;;;;GAKG;AACH,gDAGG;AAEH;;;;;;;;;;;GAWG;AACH,sCAFU,MAAM,CAEyB;AA0CzC;;;;;;;;;;;;;;GAcG;AACH;IA8JI;;;OAGG;IACH,+BAoDC;IA9MD;;;OAGG;IACH,iCAEC;IAOD;;;OAGG;IACH,6BAEC;IAuCD;;OAEG;IACH,gCAEC;IAOD;;OAEG;IACH,mCAEC;IAmDD;;OAEG;IACH,gCAEC;IA6ED;;;;OAIG;IACH,iCAEC;IAED,+BAoBC;IAED;;;;;;;;;OASG;IACH,wCAIC;IAED;;;;;;;;;;;;;;OAcG;IACH,cALW,MAAM,UACN,eAAe,GAEb,sBAAsB,CAalC;IA8DD;;;;;;;;;;;;OAYG;IACH,wBAHW,MAAM,GACJ;QAAC,gBAAgB,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAA;KAAC,GAAC,SAAS,CAqB3I;IAED;;;;;;OAMG;IACH,mBAHW,MAAM,GACJ,MAAM,GAAC,SAAS,CAU5B;IAED;;;;;;;;;OASG;IACH,0BAFW,WAAW,QAQrB;IAED;;;;;;;;;;;OAWG;IACH,cAHW,MAAM,GACJ,OAAO,CA8BnB;IA8RD;;;;;;;OAOG;IACH,eAOC;;CAgIJ;8BA78BY,OAAO,uBAAuB,EAAE,eAAe;yBAC/C,OAAO,sDAAsD,EAAE,UAAU;6BAbzD,mCAAmC;uCASzB,6BAA6B"}

package/src/shade/renderer/geometry/bvh/GPUGeometryBVHManager.js

@@ -52,6 +52,13 @@ const DATA_INITIAL_CAPACITY = round_up(1024, DATA_SIZE_ALIGNMENT);
 const DATA_GROWTH_STEP = 1024;
 const DATA_GROWTH_MULTIPLIER = 1.2;
 
+/**
+ * Words of dead shape-arena space below which a re-pack is not worth running, however large the
+ * fraction. A scene of a few small topologies churning would otherwise re-pack on every release.
+ * @type {number}
+ */
+const SHAPE_ARENA_COMPACT_FLOOR = 4096;
+
 /**
  * Regions the node arena's allocator can describe at once — live trees plus the free gaps
  * between them. A scene's live trees are one per geometry plus one per skinned instance.
@@ -182,6 +189,26 @@ export class GPUGeometryBVHManager {
     #buffer_parents_end = 0;
     #buffer_leaf_nodes_end = 0;
 
+    /**
+     * How many words of each shape arena live topologies actually occupy.
+     *
+     * The arenas are bump pointers, and a released topology used to leave its words where they
+     * were — the same story the node arena was moved off a bump pointer to fix (MEEP-009), left
+     * behind in the two arenas beside it. Streaming distinct geometries therefore grew both
+     * buffers forever: a district-by-district tour of a converted map, where the whole set is
+     * hundreds of thousands of distinct geometries, grows them monotonically until `createBuffer`
+     * refuses.
+     *
+     * The difference between this and the end pointer is the waste, and
+     * {@link #compact_shape_arenas} closes it when it is worth closing.
+     *
+     * @type {number}
+     */
+    #buffer_parents_used = 0;
+
+    /** @type {number} */
+    #buffer_leaf_nodes_used = 0;
+
     /**
      * Topology by the geometry whose nodes it was derived from, shared by every copy of it.
      *
@@ -536,12 +563,100 @@ export class GPUGeometryBVHManager {
         return true;
     }
 
+    /**
+     * Re-pack the shape arenas when enough of them is dead to be worth the pass.
+     *
+     * Half, over a floor that keeps a handful of small topologies from re-packing on every
+     * release. The re-pack is O(resident topologies) and the threshold makes it amortised: each
+     * one is paid for by at least as many words released as it moves.
+     */
+    #compact_shape_arenas_if_wasteful() {
+        const parents_waste = this.#buffer_parents_end - this.#buffer_parents_used;
+        const leaf_nodes_waste = this.#buffer_leaf_nodes_end - this.#buffer_leaf_nodes_used;
+
+        const wasteful = parents_waste > this.#buffer_parents_used
+            || leaf_nodes_waste > this.#buffer_leaf_nodes_used;
+
+        const worth_it = parents_waste + leaf_nodes_waste >= SHAPE_ARENA_COMPACT_FLOOR;
+
+        if (wasteful && worth_it) {
+            this.#compact_shape_arenas();
+        }
+    }
+
+    /**
+     * Re-pack both shape arenas so the live topologies sit at the front of them.
+     *
+     * A derivation is position-independent — it is copied into the arena verbatim and its address
+     * is recorded separately, and every consumer reaches it through {@link get_refit_target} —
+     * so a topology can be moved by writing it somewhere else and saying where. Nothing is read
+     * between the move and the republish that {@link #residency_version} asks for.
+     *
+     * Rebuilt from the source rather than read back: `bvh2_derive_topology` is a pure function of
+     * bytes the record already holds, and a readback would be a frame late.
+     *
+     * The buffers are not resized. Growing one destroys it, which an open encoder cannot survive,
+     * and this is reachable from {@link remove}; shrinking is not worth a copy of the whole arena
+     * when the space is about to be reused.
+     */
+    #compact_shape_arenas() {
+        const queue = this.#device.queue;
+
+        let parents_end = 0;
+        let leaf_nodes_end = 0;
+
+        for (const topology of this.#topology.values()) {
+            if (!topology.resident) {
+                continue;
+            }
+
+            const bytes = topology.source.bvh;
+
+            if (bytes === undefined || bytes.byteLength === 0) {
+                // the source lost its tree since; it is no longer resident in any useful sense
+                topology.resident = false;
+
+                continue;
+            }
+
+            const { parents, leaf_nodes } = bvh2_derive_topology(bytes);
+
+            topology.parents_offset = parents_end;
+            topology.leaf_nodes_offset = leaf_nodes_end;
+
+            queue.writeBuffer(
+                this.#buffer_parents,
+                parents_end * Uint32Array.BYTES_PER_ELEMENT,
+                parents, 0, parents.length
+            );
+
+            queue.writeBuffer(
+                this.#buffer_leaf_nodes,
+                leaf_nodes_end * Uint32Array.BYTES_PER_ELEMENT,
+                leaf_nodes, 0, leaf_nodes.length
+            );
+
+            parents_end += parents.length;
+            leaf_nodes_end += leaf_nodes.length;
+        }
+
+        this.#buffer_parents_end = parents_end;
+        this.#buffer_leaf_nodes_end = leaf_nodes_end;
+
+        this.#buffer_parents_used = parents_end;
+        this.#buffer_leaf_nodes_used = leaf_nodes_end;
+
+        // every offset just moved
+        this.#residency_version += 1;
+    }
+
     /**
      * Drop a shape once the last tree that had it is gone.
      *
-     * The arena bytes are not reclaimed — same append-only story as the nodes — but the map entry
-     * holds a strong reference to the geometry it is keyed by, so leaving it would keep every
-     * geometry a scene ever loaded alive for as long as the manager is.
+     * The map entry holds a strong reference to the geometry it is keyed by, so leaving it would
+     * keep every geometry a scene ever loaded alive for as long as the manager is — and its words
+     * in the two shape arenas, which are bump pointers, are given back by re-packing rather than by
+     * a free list. See {@link #buffer_parents_used}.
      *
      * @param {object} topology
      */
@@ -556,6 +671,13 @@ export class GPUGeometryBVHManager {
             if (candidate === topology) {
                 this.#topology.delete(source);
 
+                if (candidate.resident) {
+                    this.#buffer_parents_used -= candidate.node_count;
+                    this.#buffer_leaf_nodes_used -= candidate.leaf_count;
+
+                    this.#compact_shape_arenas_if_wasteful();
+                }
+
                 return;
             }
         }
@@ -710,6 +832,9 @@ export class GPUGeometryBVHManager {
             this.#buffer_parents_end += parents.length;
             this.#buffer_leaf_nodes_end += leaf_nodes.length;
 
+            this.#buffer_parents_used += parents.length;
+            this.#buffer_leaf_nodes_used += leaf_nodes.length;
+
             topology.leaf_count = leaf_nodes.length;
             // slots, not tree nodes — the arena numbers a tree's nodes with the free list's holes
             // in, and a refit's arrival counters are indexed by that numbering

package/src/shade/renderer/geometry/geometry_obtain_attribute.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Get the backing array of one `f32` attribute of a geometry, sized for `count` items, creating the
+ * attribute or resizing it if it is not that size already.
+ *
+ * This is the write-side contract a procedural generator wants: it does not care whether the geometry
+ * has been built before, only that after the call there is an array of the right length to fill.
+ *
+ * One subtlety the shape carries, and the reason it is worth having once rather than three times: the
+ * fresh-creation branch does **not** bump {@link Attribute#version}, and the reuse branch does. A newly
+ * added attribute has no uploaded copy to invalidate; an existing one does. `data` and `count` are also
+ * assigned together, and they have to be — updating one without the other produces a short draw with no
+ * error anywhere.
+ *
+ * The array is **not** preserved across a resize. The caller is expected to write every element.
+ *
+ * @param {Geometry} geometry
+ * @param {string} name attribute name, e.g. one of {@link StandardAttributes}
+ * @param {number} item_size components per vertex
+ * @param {number} count number of vertices
+ * @returns {Float32Array} the attribute's data, to be written in full
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function geometry_obtain_attribute(geometry: Geometry, name: string, item_size: number, count: number): Float32Array;
+/**
+ * Get the backing array of a geometry's index, sized for `count` indices, creating it or resizing it if
+ * it is not that size already. The `u32` counterpart of {@link geometry_obtain_attribute}, with the same
+ * contract, including that the contents are not preserved across a resize.
+ *
+ * `Geometry#index` is initialised to `null` where `getAttribute` falls off the end and returns
+ * `undefined`, which is why the two absence tests here read differently.
+ *
+ * @param {Geometry} geometry
+ * @param {number} count number of indices
+ * @returns {Uint32Array} the index's data, to be written in full
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function geometry_obtain_index(geometry: Geometry, count: number): Uint32Array;
+//# sourceMappingURL=geometry_obtain_attribute.d.ts.map

package/src/shade/renderer/geometry/geometry_obtain_attribute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geometry_obtain_attribute.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/geometry/geometry_obtain_attribute.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,oEARW,MAAM,aACN,MAAM,SACN,MAAM,GACJ,YAAY,CAwBxB;AAED;;;;;;;;;;;;;;GAcG;AACH,iEANW,MAAM,GACJ,WAAW,CAwBvB"}