@woosh/meep-engine 3.57.0 → 3.58.0

package/src/shade/renderer/global_illumination/probe/octahedral/GPUProbeAtlas.d.ts

@@ -1,10 +1,3 @@
-/**
- * @typedef {import("../../../GraphicsContext.js").GraphicsContext} GraphicsContext
- * @typedef {import("../../../scene/GPUSceneContext.js").GPUSceneContext} GPUSceneContext
- */
-/**
- * @typedef {import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
- */
 export class GPUProbeAtlas {
     /**
      *
@@ -12,25 +5,25 @@ export class GPUProbeAtlas {
      */
     constructor(device: GPUDevice);
     /**
-     *
+     * Replaced when the atlas grows; take it each frame.
      * @returns {GPUTextureContext}
      */
-    get texture_radiance(): GPUTextureContext;
+    get texture_radiance(): import("../../../texture/GPUTextureContext.js").GPUTextureContext;
     /**
      * In probes, not texels
      * @returns {number[]}
      */
     get resolution(): number[];
     /**
-     *
+     * 2 channels, first 2 moments of depth. Replaced when the atlas grows; take it each frame.
      * @return {GPUTextureContext}
      */
-    get texture_depth(): GPUTextureContext;
+    get texture_depth(): import("../../../texture/GPUTextureContext.js").GPUTextureContext;
     /**
      * Because of how reduction step works, must be a power of two
-     * @type {number}
+     * @returns {number}
      */
-    probe_resolution: number;
+    get probe_resolution(): number;
     /**
      *
      * @return {number}
@@ -42,8 +35,9 @@ export class GPUProbeAtlas {
      */
     random: () => number;
     /**
-     * NOTE: if requested atlas size is too big, we will clip to maximum size.
-     * This will lead to undefined behavior as some of the probes will not be present in the atlas
+     * Room for `probe_count` probes; the probes already there keep their texels. Past the device's
+     * height the atlas stops there and says so, and the probes past it have no home.
+     *
      * @param {number} probe_count
      */
     ensure_capacity(probe_count: number): void;
@@ -80,6 +74,6 @@ export class GPUProbeAtlas {
 }
 export type GraphicsContext = import("../../../GraphicsContext.js").GraphicsContext;
 export type GPUSceneContext = import("../../../scene/GPUSceneContext.js").GPUSceneContext;
+export type GPUTextureContext = import("../../../texture/GPUTextureContext.js").GPUTextureContext;
 export type FrameGraph = import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
-import { GPUTextureContext } from "../../../texture/GPUTextureContext.js";
 //# sourceMappingURL=GPUProbeAtlas.d.ts.map

package/src/shade/renderer/global_illumination/probe/octahedral/GPUProbeAtlas.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUProbeAtlas.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe/octahedral/GPUProbeAtlas.js"],"names":[],"mappings":"AAuBA;;;GAGG;AAEH;;GAEG;AAIH;IAyEI;;;OAGG;IACH,+BAgBC;IAtFD;;;OAGG;IACH,0CAEC;IAGD;;;OAGG;IACH,2BAUC;IAQD;;;OAGG;IACH,uCAEC;IAED;;;OAGG;IACH,kBAFU,MAAM,CAEM;IAEtB;;;OAGG;IACH,sCAGC;IAED;;;OAGG;IACH,QAFU,MAAM,MAAM,CAEM;IAgC5B;;;;OAIG;IACH,6BAFW,MAAM,QAiChB;IAED;;;;;;;;OAQG;IACH;QAHsC,WAAW,EAAtC,iBAAiB;QACU,cAAc,EAAzC,iBAAiB;aAY3B;IAED;;;;;;;OAOG;IACH;QAL+B,KAAK,EAAzB,UAAU;QACe,KAAK,EAA9B,eAAe;QACU,QAAQ,EAAjC,eAAe;QACE,gBAAgB,GAAjC,MAAM;eAgRhB;IAED,+BAGC;IAED,gBAGC;;CACJ;8BAvcY,OAAO,6BAA6B,EAAE,eAAe;8BACrD,OAAO,mCAAmC,EAAE,eAAe;yBAI3D,OAAO,iEAAiE,EAAE,UAAU;kCAnB/D,uCAAuC"}
+{"version":3,"file":"GPUProbeAtlas.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe/octahedral/GPUProbeAtlas.js"],"names":[],"mappings":"AAyCA;IAwDI;;;OAGG;IACH,+BAWC;IA9DD;;;OAGG;IACH,0FAEC;IAED;;;OAGG;IACH,2BAEC;IAED;;;OAGG;IACH,uFAEC;IAED;;;OAGG;IACH,+BAEC;IAED;;;OAGG;IACH,sCAGC;IAED;;;OAGG;IACH,QAFU,MAAM,MAAM,CAEM;IAqB5B;;;;;OAKG;IACH,6BAFW,MAAM,QAMhB;IAED;;;;;;;;OAQG;IACH;QAHsC,WAAW,EAAtC,iBAAiB;QACU,cAAc,EAAzC,iBAAiB;aAY3B;IAED;;;;;;;OAOG;IACH;QAL+B,KAAK,EAAzB,UAAU;QACe,KAAK,EAA9B,eAAe;QACU,QAAQ,EAAjC,eAAe;QACE,gBAAgB,GAAjC,MAAM;eAgRhB;IAED,+BAEC;IAED,gBAEC;;CACJ;8BA7ZY,OAAO,6BAA6B,EAAE,eAAe;8BACrD,OAAO,mCAAmC,EAAE,eAAe;gCAC3D,OAAO,uCAAuC,EAAE,iBAAiB;yBAIjE,OAAO,iEAAiE,EAAE,UAAU"}

package/src/shade/renderer/global_illumination/probe/octahedral/GPUProbeAtlas.js

@@ -2,13 +2,12 @@ import { assert } from "../../../../../core/assert.js";
 import { UINT32_MAX } from "../../../../../core/binary/UINT32_MAX.js";
 import { randomIntegerBetween } from "../../../../../core/math/random/randomIntegerBetween.js";
 import { seededRandom } from "../../../../../core/math/random/seededRandom.js";
-import { warn_limited } from "../../../../util/warn_limited.js";
 import { graph_compute_pass } from "../../../shader/graph/compute/graph_compute_pass.js";
 import { graph_image_pass } from "../../../shader/graph/graph_image_pass.js";
 import { graph_import_buffer } from "../../../shader/graph/graph_import_buffer.js";
 import { graph_import_texture } from "../../../shader/graph/graph_import_texture.js";
 import { graph_import_typed_buffer } from "../../../shader/graph/graph_import_typed_buffer.js";
-import { GPUTextureContext } from "../../../texture/GPUTextureContext.js";
+import { GPUTileAtlas2D } from "../../../texture/atlas/GPUTileAtlas2D.js";
 import { graph_lpv_paint_border_depth } from "./border/graph_lpv_paint_border_depth.js";
 import { shader_lpv_atlas_paint_borders_radiance } from "./border/shader_lpv_atlas_paint_borders_radiance.js";
 import { graph_lpv_store_sh } from "./convolve/graph_lpv_store_sh.js";
@@ -24,6 +23,7 @@ import { shader_lpv_build_gbuffer } from "./shader_lpv_build_gbuffer.js";
 /**
  * @typedef {import("../../../GraphicsContext.js").GraphicsContext} GraphicsContext
  * @typedef {import("../../../scene/GPUSceneContext.js").GPUSceneContext} GPUSceneContext
+ * @typedef {import("../../../texture/GPUTextureContext.js").GPUTextureContext} GPUTextureContext
  */
 
 /**
@@ -32,57 +32,53 @@ import { shader_lpv_build_gbuffer } from "./shader_lpv_build_gbuffer.js";
 
 // TODO initialize new probes from environment map
 
+/**
+ * Texels of a probe along each side, its 1-texel border apart. The reduction step needs a power of
+ * two.
+ * @type {number}
+ */
+const PROBE_RESOLUTION = 64;
+
 export class GPUProbeAtlas {
 
     /**
-     * @type {GPUTextureContext}
+     * The probes, a tile each with a 1-texel border for bilinear sampling: rgb9e5 radiance in
+     * `r32uint`, and the first two moments of depth in `rg16float`.
+     * @type {GPUTileAtlas2D}
      */
-    #texture_radiance;
+    #atlas;
 
     /**
-     *
+     * Replaced when the atlas grows; take it each frame.
      * @returns {GPUTextureContext}
      */
     get texture_radiance() {
-        return this.#texture_radiance;
+        return this.#atlas.texture_at(0);
     }
 
-
     /**
      * In probes, not texels
      * @returns {number[]}
      */
     get resolution() {
-        const size = this.#texture_radiance.size;
-
-        // probes have a 1 texel border to allow for bi-linear sampling
-        const padded_probe_resolution = this.padded_probe_resolution;
-
-        return [
-            Math.floor(size.width / padded_probe_resolution),
-            Math.floor(size.height / padded_probe_resolution),
-        ]
+        return [this.#atlas.tiles_per_row, this.#atlas.rows];
     }
 
     /**
-     * 2 channels, first 2 moments of depth
-     * @type {GPUTextureContext}
-     */
-    #texture_depth;
-
-    /**
-     *
+     * 2 channels, first 2 moments of depth. Replaced when the atlas grows; take it each frame.
      * @return {GPUTextureContext}
      */
     get texture_depth() {
-        return this.#texture_depth;
+        return this.#atlas.texture_at(1);
     }
 
     /**
      * Because of how reduction step works, must be a power of two
-     * @type {number}
+     * @returns {number}
      */
-    probe_resolution = 64;
+    get probe_resolution() {
+        return PROBE_RESOLUTION;
+    }
 
     /**
      *
@@ -99,72 +95,35 @@ export class GPUProbeAtlas {
      */
     random = seededRandom(1337);
 
-    /**
-     *
-     * @type {number}
-     */
-    #resolution_limit = 1024;
-
     /**
      *
      * @param {GPUDevice} device
      */
     constructor(device) {
-        this.#texture_radiance = new GPUTextureContext(device);
-        this.#texture_radiance.descriptor.usage |= GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.STORAGE_BINDING;
-        this.#texture_radiance.descriptor.format = "r32uint"; // rgb9e5 encoded
-
-        this.#texture_depth = new GPUTextureContext(device);
-        this.#texture_depth.descriptor.usage |= GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.STORAGE_BINDING;
-        this.#texture_depth.descriptor.format = "rg16float"; // first 2 moments for chebyshev's
-
-        const max_dimension = device.limits.maxTextureDimension2D;
-
-        this.#resolution_limit = max_dimension;
-        const height = this.padded_probe_resolution;
-
-        this.#texture_radiance.resize(max_dimension, height);
-        this.#texture_depth.resize(max_dimension, height);
+        const padded = this.padded_probe_resolution;
+
+        this.#atlas = new GPUTileAtlas2D({
+            device,
+            // rgb9e5 radiance; the first 2 moments of depth for Chebyshev's
+            formats: ["r32uint", "rg16float"],
+            tile_size: [padded, padded],
+            usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.STORAGE_BINDING,
+            label: "GPUProbeAtlas",
+        });
     }
 
     #update_cursor = 0;
 
     /**
-     * NOTE: if requested atlas size is too big, we will clip to maximum size.
-     * This will lead to undefined behavior as some of the probes will not be present in the atlas
+     * Room for `probe_count` probes; the probes already there keep their texels. Past the device's
+     * height the atlas stops there and says so, and the probes past it have no home.
+     *
      * @param {number} probe_count
      */
     ensure_capacity(probe_count) {
         assert.isNonNegativeInteger(probe_count, 'probe_count');
 
-        // compute current capacity
-        const res = this.#texture_radiance.size;
-
-        const existing_width = res.width;
-
-        const padded_probe_resolution = this.padded_probe_resolution;
-
-        const row_size = Math.floor(existing_width / padded_probe_resolution);
-        const col_size = Math.floor(res.height / padded_probe_resolution);
-
-        const current_capacity = row_size * col_size;
-
-        if (current_capacity >= probe_count) {
-            // do nothing
-            return;
-        }
-
-        const new_column_count = Math.ceil(probe_count / row_size);
-
-        let new_height = new_column_count * padded_probe_resolution;
-
-        if (new_height > this.#resolution_limit) {
-            warn_limited(`Can't increase atlas size beyond ${this.#resolution_limit}`);
-            new_height = this.#resolution_limit;
-        }
-
-        this.#texture_radiance.resize(existing_width, new_height);
-        this.#texture_depth.resize(existing_width, new_height);
+        this.#atlas.ensure_capacity(probe_count);
     }
 
     /**
@@ -316,7 +275,7 @@ export class GPUProbeAtlas {
          passes that filled the atlas.
         */
         let t_radiance = graph_import_texture(graph, this.texture_radiance);
-        let t_depth = graph_import_texture(graph, this.#texture_depth);
+        let t_depth = graph_import_texture(graph, this.texture_depth);
         const b_probes = graph_import_buffer(graph, scene.light_probe_volume.buffer_probes);
 
         /*
@@ -469,12 +428,10 @@ export class GPUProbeAtlas {
     }
 
     get gpu_memory_usage() {
-        return this.#texture_radiance.gpu_memory_usage
-            + this.#texture_depth.gpu_memory_usage;
+        return this.#atlas.gpu_memory_usage;
     }
 
     destroy() {
-        this.#texture_depth.destroy();
-        this.#texture_radiance.destroy();
+        this.#atlas.destroy();
     }
 }

package/src/shade/renderer/global_illumination/probe_clipmap/GPUProbeClipmapGI.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @typedef {import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
+ * @typedef {import("../../GraphicsContext.js").GraphicsContext} GraphicsContext
+ * @typedef {import("../../view/GPUViewContext.js").GPUViewContext} GPUViewContext
+ * @typedef {import("./ProbeClipmapSettings.js").ProbeClipmapSettings} ProbeClipmapSettings
+ * @typedef {import("./brick/GPUBrickClipmap.js").BrickProvider} BrickProvider
+ */
+/**
+ * {@link ShadeIndirectLightingMode.ProbeClipmap} for one view (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §5):
+ * a {@link GPUBrickClipmap}, the world as rays see it, and a {@link GPUProbeClipmap}, what shading
+ * samples, both around the view.
+ *
+ * The renderer holds one for its main view, as it holds the view's volumetrics, and hands it the view
+ * and the settings on every frame the mode runs ({@link graph_update}). The clipmaps are made on the
+ * first such frame, and made again when a frame is for another view or a structural setting has
+ * changed; {@link release} gives them back on the first frame out of the mode, and {@link destroy}
+ * with the renderer. Nothing is allocated before the mode first runs.
+ *
+ * Each frame it holds the geometry caches and card sets its scene's SDF world draws
+ * ({@link ProbeClipmapSceneHolds}), trims the caches nothing holds, and records their bake and the
+ * cards' capture (§6). Leaving the mode lets go of the holds and trims nothing, so the caches are
+ * there when the mode comes back (D28); the card sets go, and are captured again.
+ *
+ * Until its probes are traced (§13, S4) the mode lights as IBL.
+ */
+export class GPUProbeClipmapGI {
+    /**
+     * @param {GraphicsContext} graphics
+     */
+    constructor(graphics: GraphicsContext);
+    /**
+     * @returns {GPUBrickClipmap|undefined} undefined while the mode is not running
+     */
+    get brick_clipmap(): GPUBrickClipmap;
+    /**
+     * @returns {GPUProbeClipmap|undefined} undefined while the mode is not running
+     */
+    get probe_clipmap(): GPUProbeClipmap;
+    /**
+     * @returns {ProbeClipmapSceneHolds|undefined} undefined while the mode is not running
+     */
+    get holds(): ProbeClipmapSceneHolds;
+    /**
+     * Take a frame of the mode: make the clipmaps for `view` and the structure `settings` describe,
+     * unless they already are, hold the scene's geometry caches and record their bake. Allocates nothing
+     * on a frame that changes neither and has nothing to bake.
+     *
+     * @param {Object} options
+     * @param {FrameGraph} options.graph
+     * @param {GPUViewContext} options.view
+     * @param {ProbeClipmapSettings} options.settings the renderer's, read for this frame
+     * @param {number} options.depth graph handle of the view's depth, which the probes are wanted from
+     * @param {number} options.normal graph handle of the G-buffer's normals
+     * @param {*} options.stbn the 2-channel spatio-temporal blue noise, `STATIC_GRAPHICS_ENGINE_ASSETS.stbn_vec2`
+     * @param {number} options.time the caller's clock, seconds: what the probes' retention and response
+     *   times run on
+     * @param {number} [options.movers] the graph handle of the scene's mover list for the frame,
+     *   which the world's bricks are built again over
+     */
+    graph_update({ graph, view, settings, depth, normal, stbn, time, movers }: {
+        graph: FrameGraph;
+        view: GPUViewContext;
+        settings: ProbeClipmapSettings;
+        depth: number;
+        normal: number;
+        stbn: any;
+        time: number;
+        movers?: number;
+    }): void;
+    /**
+     * The debug view the settings ask for, in place of the frame's colour. Record it after
+     * {@link graph_update} in the same frame.
+     *
+     * @param {Object} options
+     * @param {FrameGraph} options.graph
+     * @param {GPUViewContext} options.view
+     * @param {ProbeClipmapSettings} options.settings
+     * @param {number[]} options.resolution
+     * @returns {number} graph handle of an `rgba8unorm` image
+     */
+    graph_debug_view({ graph, view, settings, resolution }: {
+        graph: FrameGraph;
+        view: GPUViewContext;
+        settings: ProbeClipmapSettings;
+        resolution: number[];
+    }): number;
+    /**
+     * Have a plugin write the world's bricks too, after the mesh provider and every provider added
+     * before it, over the same taken cells (§7.6).
+     *
+     * @param {BrickProvider} provider
+     */
+    add_provider(provider: BrickProvider): void;
+    /**
+     * @param {BrickProvider} provider
+     * @returns {boolean} whether it had been added
+     */
+    remove_provider(provider: BrickProvider): boolean;
+    /**
+     * Give back everything the mode holds, as on the first frame out of it: the clipmaps, and the holds
+     * on the geometry caches, which stay baked. The next {@link graph_update} starts again from nothing.
+     */
+    release(): void;
+    destroy(): void;
+    #private;
+}
+export type FrameGraph = import("../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+export type GraphicsContext = import("../../GraphicsContext.js").GraphicsContext;
+export type GPUViewContext = import("../../view/GPUViewContext.js").GPUViewContext;
+export type ProbeClipmapSettings = import("./ProbeClipmapSettings.js").ProbeClipmapSettings;
+export type BrickProvider = import("./brick/GPUBrickClipmap.js").BrickProvider;
+import { GPUBrickClipmap } from "./brick/GPUBrickClipmap.js";
+import { GPUProbeClipmap } from "./probe/GPUProbeClipmap.js";
+import { ProbeClipmapSceneHolds } from "./ProbeClipmapSceneHolds.js";
+//# sourceMappingURL=GPUProbeClipmapGI.d.ts.map

package/src/shade/renderer/global_illumination/probe_clipmap/GPUProbeClipmapGI.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GPUProbeClipmapGI.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/probe_clipmap/GPUProbeClipmapGI.js"],"names":[],"mappings":"AAWA;;;;;;GAMG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH;IAmDI;;OAEG;IACH,sBAFW,eAAe,EAMzB;IAED;;OAEG;IACH,qCAEC;IAED;;OAEG;IACH,qCAEC;IAED;;OAEG;IACH,oCAEC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH;QAX+B,KAAK,EAAzB,UAAU;QACc,IAAI,EAA5B,cAAc;QACgB,QAAQ,EAAtC,oBAAoB;QACJ,KAAK,EAArB,MAAM;QACU,MAAM,EAAtB,MAAM;QACK,IAAI;QACC,IAAI,EAApB,MAAM;QAEW,MAAM,GAAvB,MAAM;aAkGhB;IAED;;;;;;;;;;OAUG;IACH;QAN+B,KAAK,EAAzB,UAAU;QACc,IAAI,EAA5B,cAAc;QACgB,QAAQ,EAAtC,oBAAoB;QACF,UAAU,EAA5B,MAAM,EAAE;QACN,MAAM,CAmBlB;IAED;;;;;OAKG;IACH,uBAFW,aAAa,QASvB;IAED;;;OAGG;IACH,0BAHW,aAAa,GACX,OAAO,CAanB;IAyCD;;;OAGG;IACH,gBAoBC;IAED,gBAQC;;CACJ;yBApWY,OAAO,8DAA8D,EAAE,UAAU;8BACjF,OAAO,0BAA0B,EAAE,eAAe;6BAClD,OAAO,8BAA8B,EAAE,cAAc;mCACrD,OAAO,2BAA2B,EAAE,oBAAoB;4BACxD,OAAO,4BAA4B,EAAE,aAAa;gCAf/B,4BAA4B;gCAM5B,4BAA4B;uCAErB,6BAA6B"}