@woosh/meep-engine 3.57.0 → 3.58.0

package/src/shade/renderer/global_illumination/probe_clipmap/debug/graph_probe_clipmap_debug_mesh_sdf.js

@@ -0,0 +1,138 @@
+import { assert } from "../../../../../core/assert.js";
+import { TextureResourceDescriptor } from "../../../../device/graph/TextureResourceDescriptor.js";
+import { CAMERA_UNIFORM_STRUCT } from "../../../camera/CAMERA_UNIFORM_STRUCT.js";
+import {
+    MESH_SDF_ATLAS_RESOURCE,
+    MESH_SDF_HEADERS_RESOURCE,
+    MESH_SDF_INDIRECTION_RESOURCE,
+    MESH_SDF_SAMPLER_RESOURCE
+} from "../../../geometry/sdf/MESH_SDF_RESOURCES.js";
+import { BVH_STRUCT } from "../../../shader/chunk/bvh/BVH_STRUCT.js";
+import { chunk_camera_ray_from_uv } from "../../../shader/chunk/geometry/ray/chunk_camera_ray_from_uv.js";
+import { F32_MAX_DEFINITION } from "../../../shader/chunk/math/F32_MAX_DEFINITION.js";
+import { chunk_scene_sdf_raymarch } from "../../../shader/chunk/sdf/chunk_scene_sdf_raymarch.js";
+import { CodeChunk } from "../../../shader/compiler/CodeChunk.js";
+import { ImageShader } from "../../../shader/ImageShader.js";
+import { ShaderResourceSetDescriptor } from "../../../shader/resource/ShaderResourceSetDescriptor.js";
+import { ShaderDescriptor } from "../../../shader/ShaderDescriptor.js";
+import { u32 } from "../../../shader/type/WEBGPU_WGSL_PRIMITIVE_TYPES.js";
+import { WebGPUArray } from "../../../shader/type/WebGPUArray.js";
+
+/**
+ * @typedef {import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph} FrameGraph
+ * @typedef {import("../../../view/GPUViewContext.js").GPUViewContext} GPUViewContext
+ */
+
+/**
+ * Past this a ray has hit nothing; it only keeps the hit point finite for the derivatives.
+ * @type {number}
+ */
+const FAR = 1e4;
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    .add(MESH_SDF_HEADERS_RESOURCE)
+    .add(MESH_SDF_INDIRECTION_RESOURCE)
+    .add(MESH_SDF_ATLAS_RESOURCE)
+    .add(MESH_SDF_SAMPLER_RESOURCE)
+    .addStorageBuffer("scene_database", WebGPUArray.from(u32))
+    .addStorageBuffer("tlas", BVH_STRUCT);
+
+resources.createGroup()
+    .addUniform("camera", CAMERA_UNIFORM_STRUCT);
+
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+@fragment
+fn main(
+  @builtin(position) coord: vec4<f32>,
+  @location(0) uv: vec2<f32>,
+) -> @location(0) vec4<f32> {
+    let ray = camera_ray_from_uv(uv, camera);
+
+    let t = scene_sdf_raymarch(ray);
+    let hit = t < F32_MAX;
+
+    // in uniform control flow, for the derivatives: a missed pixel's point is far and unused
+    let point = ray.origin + min(t, ${FAR.toFixed(1)}) * ray.direction;
+    let normal = normalize(cross(dpdx(point), dpdy(point)));
+
+    if (!hit) {
+        return vec4<f32>(0.08, 0.08, 0.1, 1.0);
+    }
+
+    // the surface normal as a colour, dimmed with distance so that depth reads
+    let shade = 0.5 + 0.5 * normal;
+    let fade = 1.0 / (1.0 + 0.02 * t);
+
+    return vec4<f32>(shade * (0.35 + 0.65 * fade), 1.0);
+}
+`, [
+        F32_MAX_DEFINITION,
+        chunk_camera_ray_from_uv,
+        chunk_scene_sdf_raymarch,
+    ]);
+
+/**
+ * The view's scene through its geometry caches alone: each pixel's camera ray walks the TLAS and,
+ * in every instance it meets, marches that geometry's sparse field at level 0 (`mesh_sdf_raymarch`)
+ * — the bricks a bake has stored so far, EMPTY ones read as the band. The nearest hit is shaded by
+ * its normal. A geometry with no cache yet draws nothing, so the view shows the caches filling.
+ *
+ * @type {ImageShader}
+ */
+export const shader_probe_clipmap_debug_mesh_sdf = new ImageShader({
+    descriptor: ShaderDescriptor.from({
+        label: "Probe Clipmap Debug / Mesh SDF",
+        resources,
+        body,
+    }),
+    targets: [{
+        format: "rgba8unorm"
+    }]
+});
+
+/**
+ * @param {Object} options
+ * @param {FrameGraph} options.graph
+ * @param {GPUViewContext} options.view
+ * @param {number[]} options.resolution
+ * @returns {number} graph handle of the `rgba8unorm` image
+ */
+export function graph_probe_clipmap_debug_mesh_sdf({ graph, view, resolution }) {
+    assert.defined(graph, 'graph');
+    assert.defined(view, 'view');
+    assert.isArrayLike(resolution, 'resolution');
+
+    const data = {};
+
+    const pass = graph.add("Probe Clipmap Debug / Mesh SDF", data, (data, resources, context) => {
+        const scene = view.scene;
+        const output = resources.get(data.output);
+
+        shader_probe_clipmap_debug_mesh_sdf.draw({
+            encoder: context.encoder,
+            bindings: scene.geometries.sdf.write_bindings({
+                scene_database: scene.scene_database_buffer,
+                tlas: scene.tlas.buffer,
+                camera: view.camera.buffer,
+            }),
+            colorAttachments: [{
+                loadOp: "clear",
+                storeOp: "store",
+                clearValue: [0, 0, 0, 1],
+                view: output.obtainView(),
+            }],
+        });
+    });
+
+    data.output = pass.create("probe_clipmap_debug", TextureResourceDescriptor.from({
+        format: "rgba8unorm",
+        resolution,
+        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT,
+    }));
+
+    return data.output;
+}

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

@@ -0,0 +1,170 @@
+/**
+ * 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 holds a probe only while something on
+ * screen wants it, so probes are a sparse cache over the lattice.
+ *
+ * **Storage** (§8.2):
+ * - {@link indirection}, `r32uint`, a texel a lattice point in storage that wraps, the cascades
+ *   stacked along z: the slot of the point's probe, or none. Allocated whole, since the lattice follows
+ *   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 64-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.
+ * - 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 or that nobody wanted for `retention_time`, want marks the cages one pixel of each
+ * screen tile reads, admit gives each wanted point without a probe a NEW one, schedule sets the period
+ * T from the wanted count, and the due passes list the frame's updates, NEW probes first.
+ *
+ * **The frame's update** (§8.4, §8.6), once the brick clipmap is built: relocate, then trace, a ray a
+ * thread, R a probe, each with its hit and the suns' soft shadows there.
+ *
+ * Retire, admit, due and the update run through commands written on the device, want over the screen's
+ * 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
+ * counted on the device and read back, and the next frame doubles the capacity (§7.10's pattern). Nothing
+ * shrinks.
+ */
+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.spacing metres
+     * @param {number} options.radiance_resolution a power of two
+     * @param {number} options.depth_resolution a power of two
+     */
+    constructor(device: GPUDevice, { cascade_count, resolution, spacing, radiance_resolution, depth_resolution }: {
+        cascade_count: number;
+        resolution: number;
+        spacing: number;
+        radiance_resolution: number;
+        depth_resolution: number;
+    });
+    /**
+     * @type {number}
+     * @readonly
+     */
+    readonly cascade_count: number;
+    /**
+     * Lattice points per axis of a cascade.
+     * @type {number}
+     * @readonly
+     */
+    readonly resolution: number;
+    /**
+     * Metres between probes in the finest cascade.
+     * @type {number}
+     * @readonly
+     */
+    readonly spacing: number;
+    /**
+     * Octahedral radiance texels per side of a probe.
+     * @type {number}
+     * @readonly
+     */
+    readonly radiance_resolution: number;
+    /**
+     * Octahedral depth-moment texels per side of a probe.
+     * @type {number}
+     * @readonly
+     */
+    readonly depth_resolution: number;
+    /**
+     * @returns {GPUTexture}
+     */
+    get indirection(): GPUTexture;
+    /**
+     * 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
+     * short of the lattice's on each axis (`PROBE_LEVELS_RESOURCE`).
+     * @returns {GPUBuffer}
+     */
+    get levels(): GPUBuffer;
+    /**
+     * Slots: the probes there can be before the capacity grows.
+     * @returns {number}
+     */
+    get capacity(): number;
+    /**
+     * @param {number} cascade
+     * @param {number} axis
+     * @returns {number} the cascade's lattice window's least point on the axis, in its spacing
+     */
+    corner(cascade: number, axis: number): number;
+    /**
+     * @param {number} cascade
+     * @returns {number} metres between the cascade's probes
+     */
+    cell_size(cascade: number): number;
+    /**
+     * @param {ProbeClipmapSettings} settings
+     * @returns {boolean} whether this is what the settings' probe cascades and probes describe
+     */
+    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.
+     *
+     * @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 {*} 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.time the caller's clock, seconds
+     * @param {number} options.retention_time seconds an unwanted probe keeps its slot
+     * @param {number} options.response_time seconds of the blend's response, τ (§8.8)
+     * @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
+     *   rays see, built this frame
+     * @param {number} options.bricks the graph handle of the brick clipmap's last write this frame, which
+     *   the update orders after
+     * @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 {import("../../../material/resident/GPUResidentMaterialContext.js").GPUResidentMaterialContext} options.materials
+     *   the resident materials, updated this frame: what a hit no card sees takes
+     * @param {GPUBuffer} options.card_rows the row → card set table, a word a `meshes` row
+     */
+    graph_update({ graph, x, y, z, depth, normal, camera, stbn, resolution, time, retention_time, response_time, ray_budget, rays_per_probe, brick_clipmap, bricks, scene, materials, card_rows }: {
+        graph: FrameGraph;
+        x: number;
+        y: number;
+        z: number;
+        depth: number;
+        normal: number;
+        camera: GPUBuffer;
+        stbn: any;
+        resolution: ArrayLike<number>;
+        time: number;
+        retention_time: number;
+        response_time: number;
+        ray_budget: number;
+        rays_per_probe: number;
+        brick_clipmap: import("../brick/GPUBrickClipmap.js").GPUBrickClipmap;
+        bricks: number;
+        scene: import("../../../scene/GPUSceneContext.js").GPUSceneContext;
+        materials: import("../../../material/resident/GPUResidentMaterialContext.js").GPUResidentMaterialContext;
+        card_rows: GPUBuffer;
+    }): void;
+    destroy(): void;
+    #private;
+}
+export type ProbeClipmapSettings = import("../ProbeClipmapSettings.js").ProbeClipmapSettings;
+export type FrameGraph = import("../../../../../engine/graphics/render/frame_graph/FrameGraph.js").FrameGraph;
+//# sourceMappingURL=GPUProbeClipmap.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"GPUProbeClipmap.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/global_illumination/probe_clipmap/probe/GPUProbeClipmap.js"],"names":[],"mappings":"AAgFA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH;IA4KI;;;;;;;;OAQG;IACH;QAN2B,aAAa,EAA7B,MAAM;QACU,UAAU,EAA1B,MAAM;QACU,OAAO,EAAvB,MAAM;QACU,mBAAmB,EAAnC,MAAM;QACU,gBAAgB,EAAhC,MAAM;OAyFhB;IA3QD;;;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;IA6OjB;;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH;QAxB+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,IAAI,EAApB,MAAM;QACU,cAAc,EAA9B,MAAM;QACU,aAAa,EAA7B,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;QAE4C,SAAS,EAAhH,OAAO,0DAA0D,EAAE,0BAA0B;QAE1E,SAAS;aA8JtC;IAqVD,gBAcC;;CACJ;mCAl6BY,OAAO,4BAA4B,EAAE,oBAAoB;yBACzD,OAAO,iEAAiE,EAAE,UAAU"}