@woosh/meep-engine 3.60.5 → 3.60.7

package/src/shade/renderer/global_illumination/probe_clipmap/probe/GPUProbeClipmap.d.ts

@@ -1,9 +1,12 @@
 /**
  * What shading samples (PROBE_CLIPMAP_PROPOSAL_2026_10_27.md §8): {@link cascade_count} cascades of
  * {@link resolution}³ lattice points around the view, {@link spacing} metres apart in the finest
- * cascade and twice as far apart in each one around it. A point gets a probe when a pixel wants it, or
- * a hit of a probe a pixel wants, and keeps it until its window leaves it or the slots are wanted for
- * others, so probes are a sparse cache over the lattice.
+ * cascade and twice as far apart in each one around it. A point gets a probe when its wants want it, and
+ * keeps it until its window leaves it or the slots are wanted for others, so probes are a sparse cache
+ * over the lattice. Two of them make the mode (WORLD_PROBE_CACHE_SCOPE_2026_11_01.md): the frustum's probes,
+ * wanted by the frame's pixels ({@link ProbeClipmapScreenWants}), and the world cache, wanted by the
+ * frustum's hits where the frustum has no probe ({@link ProbeClipmapHitWants}), its windows the frustum's at
+ * 2^k its lattice ({@link place_within}).
  *
  * **Storage** (§8.2):
  * - {@link indirection}, `r32uint`, a texel a lattice point in storage that wraps, the cascades
@@ -11,22 +14,25 @@
  *   from the structure alone.
  * - a slot each: a state of two words, the kind and updates and then where relocation moved it
  *   (`PROBE_CLIPMAP.js`), a 48-byte record (`PROBE_RECORD_STRUCT`), an octahedral radiance tile of
- *   {@link radiance_resolution}² texels and a depth-moment tile of {@link depth_resolution}², each with
- *   a one-texel skirt, in two 2-D tile atlases. The slots are handed out by a free list on the device.
+ *   {@link radiance_resolution}² texels and a depth-moment tile of {@link depth_resolution}², in two 2-D
+ *   tile atlases. The depth tile has a one-texel skirt, which the pick's bilinear tap reads; the radiance
+ *   tile has one where {@link radiance_skirt}, for the specular's tap, and none where nothing samples it.
+ *   The slots are handed out by a free list on the device.
  * - the active lists, double-buffered: each frame's retire reads the last frame's and writes the
  *   frame's; a wanted bit a lattice point and the wanted list, made again every frame; the trace list
  *   of the frame's updates, at most U = ⌊ray_budget / rays_per_probe⌋.
  *
- * **A frame's lifetime** ({@link graph_update}, §8.3, §8.5): the windows are placed around the anchor,
- * coarsest first, each a parent cell inside its parent. Retire frees the probes whose points left
- * their windows and those the last frame's schedule evicted, want marks the cages one pixel of each
- * screen tile reads, the hits' wants the cages the last frame's hits read their bounce from, admit
+ * **A frame's windows** ({@link place}, {@link place_within}): around the anchor, coarsest first, each a
+ * parent cell inside its parent; or another clipmap's.
+ *
+ * **A frame's lifetime** ({@link graph_update}, §8.3, §8.5): retire frees the probes whose points left
+ * their windows and those the last frame's schedule evicted, the wants mark the cages they read, admit
  * gives each wanted point without a probe a NEW one, schedule sets the period T from the probes waiting
  * for an update and the next frame's eviction from the pressure on the slots (`PROBE_FREE_SLACK`), and
  * the due passes list the frame's updates, NEW probes first.
  *
  * **The frame's rays** (§8.6): the lifetime's last passes lay them out. Each listed probe's rays this update
- * are a count the budget does not scale (a uniform update's R, a DEAD probe's fewest) and a request it
+ * are a count the budget does not scale (a uniform update's R, a DEAD probe's `PROBE_DEAD_RAYS`) and a request it
  * does (a guided update's, `probe_requests`, which projection sets after each update). Both are scanned
  * (`graph_prefix_scan_csdldf`'s shaders), the requests are scaled into what the budget leaves, and the
  * sums of the two are `probe_ray_sums`: a probe's rays follow one another in the trace list's order, and
@@ -34,13 +40,13 @@
  *
  * **The frame's update** (§8.4, §8.6), once the brick clipmap is built: relocate; then the guide, the
  * CDF over each listed probe's history that its guided updates' rays follow (`PROBE_UNIFORM_PERIOD`);
- * then trace, a ray a thread, each with its hit and the suns' shadow rays from there.
+ * then trace, a ray a thread, each with its hit and the suns' shadow rays from there; shade, the local
+ * lights, and the bounce from two clipmaps, the second where the first has no probe (§8.7).
  *
- * Retire, admit, due and the update run through commands written on the device, want over the screen's
+ * Retire, admit, due and the update run through commands written on the device, the screen's wants over its
  * tiles: nothing is sized by the capacity.
  *
- * **Capacity** starts at `2·N²·C` slots, rounded up to a power of two: a visible surface crosses each
- * cascade as a shell a cell thick, doubled for the cage. An admission the free list could not serve is
+ * **Capacity** starts at what its maker gives, a power of two. An admission the free list could not serve is
  * counted on the device and read back, and the next frame doubles the capacity (§7.10's pattern). Nothing
  * shrinks.
  */
@@ -48,18 +54,30 @@ export class GPUProbeClipmap {
     /**
      * @param {GPUDevice} device
      * @param {object} options
-     * @param {number} options.cascade_count
-     * @param {number} options.resolution one of {@link PROBE_CLIPMAP_CASCADE_RESOLUTIONS}
+     * @param {number} options.cascade_count at most the levels table holds, {@link CLIPMAP_LEVEL_LIMIT}, and
+     *        the record's cascade field, {@link PROBE_RECORD_CASCADE_SHIFT}
+     * @param {number} options.resolution a power of two, at most 1024: the order's Morton code takes 10 bits
+     *        an axis; the indirection's height, resolution · cascade_count, at most the device's
+     *        `maxTextureDimension3D`
      * @param {number} options.spacing metres
-     * @param {number} options.radiance_resolution a power of two
+     * @param {number} options.radiance_resolution a power of two from 2, which the update's bit-reversed
+     *        walk of the texels needs
      * @param {number} options.depth_resolution a power of two
+     * @param {boolean} options.radiance_skirt whether a radiance tile has a skirt for a reader's bilinear tap
+     *   (`chunk_probe_clipmap_sample_radiance`): a clipmap whose radiance nothing samples has none
+     * @param {string} options.label what its GPU objects' labels begin with
+     * @param {number} options.capacity the slots it starts with, a power of two: a start, which admissions the
+     *   free list cannot serve grow
      */
-    constructor(device: GPUDevice, { cascade_count, resolution, spacing, radiance_resolution, depth_resolution }: {
+    constructor(device: GPUDevice, { cascade_count, resolution, spacing, radiance_resolution, depth_resolution, radiance_skirt, label, capacity }: {
         cascade_count: number;
         resolution: number;
         spacing: number;
         radiance_resolution: number;
         depth_resolution: number;
+        radiance_skirt: boolean;
+        label: string;
+        capacity: number;
     });
     /**
      * @type {number}
@@ -90,6 +108,19 @@ export class GPUProbeClipmap {
      * @readonly
      */
     readonly depth_resolution: number;
+    /**
+     * Whether a radiance tile has a skirt of a texel, which a reader's bilinear tap needs; a clipmap whose
+     * radiance is only loaded texel by texel, never sampled, has none.
+     * @type {boolean}
+     * @readonly
+     */
+    readonly radiance_skirt: boolean;
+    /**
+     * What its GPU objects' labels begin with.
+     * @type {string}
+     * @readonly
+     */
+    readonly label: string;
     /**
      * Put what the probes' readers bind into `bindings`, under the names `chunk_probe_clipmap_pick` reads
      * them by: the levels and the sampling uniforms, the indirection, the states and records, the depth
@@ -104,6 +135,28 @@ export class GPUProbeClipmap {
      * @returns {GPUTexture}
      */
     get indirection(): GPUTexture;
+    /**
+     * The last update's probes, in its order: the list the rays name their probe by. With {@link origins},
+     * {@link rays} and {@link dispatch}, what another clipmap's hits' wants read (`ProbeClipmapHitWants`),
+     * before this clipmap's next lifetime writes them over.
+     * @returns {GPUBuffer}
+     */
+    get trace(): GPUBuffer;
+    /**
+     * Where relocation left each of the last update's probes, `vec4<f32>(origin, spacing)`.
+     * @returns {GPUBuffer}
+     */
+    get origins(): GPUBuffer;
+    /**
+     * The last update's rays, `PROBE_RAY_STRUCT`.
+     * @returns {GPUBuffer}
+     */
+    get rays(): GPUBuffer;
+    /**
+     * The indirect commands, `PROBE_DISPATCH_RAYS` the last update's rays' launch among them.
+     * @returns {GPUBuffer}
+     */
+    get dispatch(): GPUBuffer;
     /**
      * The cascades' cage windows, a {@link CLIPMAP_LEVEL_ARRAY} as a uniform, finest first, as placed by
      * the last {@link graph_update}: a cell is a cage of eight lattice points, so a window is one cell
@@ -119,7 +172,7 @@ export class GPUProbeClipmap {
     /**
      * @param {number} cascade
      * @param {number} axis
-     * @returns {number} the cascade's lattice window's least point on the axis, in its spacing
+     * @returns {number} the cascade's lattice window's least point on the axis, in its spacing, as last placed
      */
     corner(cascade: number, axis: number): number;
     /**
@@ -133,21 +186,33 @@ export class GPUProbeClipmap {
      */
     built_for(settings: ProbeClipmapSettings): boolean;
     /**
-     * Record the frame's lifetime (§8.3): place the windows around the anchor, retire, want from the
-     * G-buffer, admit and schedule; then, once the bricks are built, its updates: relocate, trace and
-     * shade the listed probes' rays (§8.4–§8.7). Allocates nothing per frame.
+     * Place the windows around the anchor, coarsest first, each a parent cell inside its parent, for the
+     * frame's {@link graph_update}.
+     *
+     * @param {number} x the anchor, world metres
+     * @param {number} y
+     * @param {number} z
+     */
+    place(x: number, y: number, z: number): void;
+    /**
+     * Take another clipmap's windows, as {@link place} last placed them, at 2^k this clipmap's lattice
+     * (WORLD_PROBE_CACHE_SCOPE_2026_11_01.md §1.2): the same cascades, each the other's window and spacing over
+     * 2^k, its corner 2^k the other's, so every point of the other's lattice is one of this clipmap's and the
+     * two scroll together. k is the ratio of the resolutions, a power of two from 2.
+     *
+     * @param {GPUProbeClipmap} clipmap placed this frame
+     */
+    place_within(clipmap: GPUProbeClipmap): void;
+    /**
+     * Record the frame's lifetime in the windows {@link place} or {@link place_within} placed this frame
+     * (§8.3): retire, the wants, admit and schedule; then, once the bricks are built, its updates: relocate,
+     * trace, shade, light and bounce the listed probes' rays (§8.4–§8.7). Allocates nothing per frame.
      *
      * @param {Object} options
      * @param {FrameGraph} options.graph
-     * @param {number} options.x the anchor, world metres
-     * @param {number} options.y
-     * @param {number} options.z
-     * @param {number} options.depth graph handle of the frame's depth
-     * @param {number} options.normal graph handle of the G-buffer's normals
-     * @param {GPUBuffer} options.camera the view's camera uniform
+     * @param {ProbeClipmapWants} options.wants who wants the frame's probes
      * @param {*} options.stbn the 2-channel spatio-temporal blue noise, `STATIC_GRAPHICS_ENGINE_ASSETS.stbn_vec2`
-     * @param {ArrayLike<number>} options.resolution the frame's pixels, x and y
-     * @param {number} options.response_frames frames of the blend's response, τ (§8.8)
+     * @param {number} options.response_frames frames over which a re-sampled neighbour's history goes stale, τ
      * @param {number} options.ray_budget rays a frame
      * @param {number} options.rays_per_probe rays an update, R: the frame updates ⌊ray_budget / R⌋ probes at most
      * @param {import("../brick/GPUBrickClipmap.js").GPUBrickClipmap} options.brick_clipmap the world the
@@ -157,19 +222,19 @@ export class GPUProbeClipmap {
      * @param {import("../../../scene/GPUSceneContext.js").GPUSceneContext} options.scene the scene the rays
      *   light and shade: its lights, its environment, its rows and their geometry caches' cards
      * @param {GPUBuffer} options.card_rows the row → card set table, a word a `meshes` row
-     * @param {boolean} options.resampling whether each update re-samples its neighbours, adding what they have
-     *   seen to its rays (`shader_probe_clipmap_resample`)
+     * @param {boolean} options.history_resampling whether each update re-samples its neighbours' histories, adding
+     *   what they have seen to its rays (`shader_probe_clipmap_resample`); never where the radiance has no skirt
+     * @param {boolean} options.ray_resampling whether each update re-samples one neighbour's rays of the frame,
+     *   adding them to its own (`shader_probe_clipmap_candidate`, `shader_probe_clipmap_resample_rays`)
+     * @param {{lookup: number, data: number}} options.clusters graph handles of the world light clusters over the
+     *   bricks' cascades, which the hits' local lights come from
+     * @param {GPUProbeClipmap} options.bounce_first the clipmap a hit takes its next bounce from first
+     * @param {GPUProbeClipmap} options.bounce_fallback the clipmap it takes it from where the first has no probe
      */
-    graph_update({ graph, x, y, z, depth, normal, camera, stbn, resolution, response_frames, ray_budget, rays_per_probe, brick_clipmap, bricks, scene, card_rows, resampling }: {
+    graph_update({ graph, wants, stbn, response_frames, ray_budget, rays_per_probe, brick_clipmap, bricks, scene, card_rows, history_resampling, ray_resampling, clusters, bounce_first, bounce_fallback }: {
         graph: FrameGraph;
-        x: number;
-        y: number;
-        z: number;
-        depth: number;
-        normal: number;
-        camera: GPUBuffer;
+        wants: ProbeClipmapWants;
         stbn: any;
-        resolution: ArrayLike<number>;
         response_frames: number;
         ray_budget: number;
         rays_per_probe: number;
@@ -177,11 +242,19 @@ export class GPUProbeClipmap {
         bricks: number;
         scene: import("../../../scene/GPUSceneContext.js").GPUSceneContext;
         card_rows: GPUBuffer;
-        resampling: boolean;
+        history_resampling: boolean;
+        ray_resampling: boolean;
+        clusters: {
+            lookup: number;
+            data: number;
+        };
+        bounce_first: GPUProbeClipmap;
+        bounce_fallback: GPUProbeClipmap;
     }): void;
     destroy(): void;
     #private;
 }
 export type ProbeClipmapSettings = import("../ProbeClipmapSettings.js").ProbeClipmapSettings;
 export type FrameGraph = import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+export type ProbeClipmapWants = import("./ProbeClipmapScreenWants.js").ProbeClipmapScreenWants | import("./ProbeClipmapHitWants.js").ProbeClipmapHitWants;
 //# sourceMappingURL=GPUProbeClipmap.d.ts.map

package/src/shade/renderer/global_illumination/probe_clipmap/probe/GPUProbeClipmap.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPUProbeClipmap.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/GPUProbeClipmap.js"],"names":[],"mappings":"AAoHA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH;IAqOI;;;;;;;;OAQG;IACH;QAN2B,aAAa,EAA7B,MAAM;QACU,UAAU,EAA1B,MAAM;QACU,OAAO,EAAvB,MAAM;QACU,mBAAmB,EAAnC,MAAM;QACU,gBAAgB,EAAhC,MAAM;OAmGhB;IA9UD;;;OAGG;IACH,wBAHU,MAAM,CAGF;IAEd;;;;OAIG;IACH,qBAHU,MAAM,CAGL;IAEX;;;;OAIG;IACH,kBAHU,MAAM,CAGR;IAER;;;;OAIG;IACH,8BAHU,MAAM,CAGI;IAEpB;;;;OAIG;IACH,2BAHU,MAAM,CAGC;IAgTjB;;;;;;;;OAQG;IACH,4CAUC;IAED;;OAEG;IACH,8BAEC;IAED;;;;;OAKG;IACH,wBAEC;IAED;;;OAGG;IACH,uBAEC;IAED;;;;OAIG;IACH,gBAJW,MAAM,QACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,oBAHW,oBAAoB,GAClB,OAAO,CAQnB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH;QAtB+B,KAAK,EAAzB,UAAU;QACM,CAAC,EAAjB,MAAM;QACU,CAAC,EAAjB,MAAM;QACU,CAAC,EAAjB,MAAM;QACU,KAAK,EAArB,MAAM;QACU,MAAM,EAAtB,MAAM;QACa,MAAM;QACd,IAAI;QACY,UAAU,EAArC,UAAU,MAAM,CAAC;QACD,eAAe,EAA/B,MAAM;QACU,UAAU,EAA1B,MAAM;QACU,cAAc,EAA9B,MAAM;QACyD,aAAa,EAA5E,OAAO,6BAA6B,EAAE,eAAe;QAErC,MAAM,EAAtB,MAAM;QAE+D,KAAK,EAA1E,OAAO,mCAAmC,EAAE,eAAe;QAExC,SAAS;QACX,UAAU,EAA3B,OAAO;aA+OjB;IAweD,gBAcC;;CACJ;mCA5uCY,OAAO,4BAA4B,EAAE,oBAAoB;yBACzD,OAAO,iEAAiE,EAAE,UAAU"}
+{"version":3,"file":"GPUProbeClipmap.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/GPUProbeClipmap.js"],"names":[],"mappings":"AAiIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH;IA4QI;;;;;;;;;;;;;;;;;OAiBG;IACH;QAf2B,aAAa,EAA7B,MAAM;QAEU,UAAU,EAA1B,MAAM;QAGU,OAAO,EAAvB,MAAM;QACU,mBAAmB,EAAnC,MAAM;QAEU,gBAAgB,EAAhC,MAAM;QACW,cAAc,EAA/B,OAAO;QAES,KAAK,EAArB,MAAM;QACU,QAAQ,EAAxB,MAAM;OA8GhB;IAxYD;;;OAGG;IACH,wBAHU,MAAM,CAGF;IAEd;;;;OAIG;IACH,qBAHU,MAAM,CAGL;IAEX;;;;OAIG;IACH,kBAHU,MAAM,CAGR;IAER;;;;OAIG;IACH,8BAHU,MAAM,CAGI;IAEpB;;;;OAIG;IACH,2BAHU,MAAM,CAGC;IAEjB;;;;;OAKG;IACH,yBAHU,OAAO,CAGF;IAEf;;;;OAIG;IACH,gBAHU,MAAM,CAGV;IA2VN;;;;;;;;OAQG;IACH,4CAUC;IAED;;OAEG;IACH,8BAEC;IAED;;;;;OAKG;IACH,uBAEC;IAED;;;OAGG;IACH,yBAEC;IAED;;;OAGG;IACH,sBAEC;IAGD;;;OAGG;IACH,0BAEC;IAED;;;;;OAKG;IACH,wBAEC;IAED;;;OAGG;IACH,uBAEC;IAED;;;;OAIG;IACH,gBAJW,MAAM,QACN,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,mBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,oBAHW,oBAAoB,GAClB,OAAO,CAQnB;IAED;;;;;;;OAOG;IACH,SAJW,MAAM,KACN,MAAM,KACN,MAAM,QA6BhB;IAED;;;;;;;OAOG;IACH,sBAFW,eAAe,QA2BzB;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH;QAtB+B,KAAK,EAAzB,UAAU;QACiB,KAAK,EAAhC,iBAAiB;QACN,IAAI;QACC,eAAe,EAA/B,MAAM;QACU,UAAU,EAA1B,MAAM;QACU,cAAc,EAA9B,MAAM;QACyD,aAAa,EAA5E,OAAO,6BAA6B,EAAE,eAAe;QAErC,MAAM,EAAtB,MAAM;QAE+D,KAAK,EAA1E,OAAO,mCAAmC,EAAE,eAAe;QAExC,SAAS;QACX,kBAAkB,EAAnC,OAAO;QAEU,cAAc,EAA/B,OAAO;QAEiC,QAAQ,EAAhD;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAC;QAEL,YAAY,EAArC,eAAe;QACU,eAAe,EAAxC,eAAe;aAiOzB;IAshBD,gBAcC;;CACJ;mCAz7CY,OAAO,4BAA4B,EAAE,oBAAoB;yBACzD,OAAO,iEAAiE,EAAE,UAAU;gCACpF,OAAO,8BAA8B,EAAE,uBAAuB,GAAC,OAAO,2BAA2B,EAAE,oBAAoB"}