@woosh/meep-engine 3.65.0 → 3.68.0

package/src/shade/renderer/global_illumination/screen_probe/ScreenProbeSettings.js

@@ -0,0 +1,197 @@
+import { assert } from "../../../../core/assert.js";
+import { isPowerOfTwo } from "../../../../core/math/isPowerOfTwo.js";
+import { SCREEN_PROBE_OCTAHEDRON_LIMIT, SCREEN_PROBE_OCTAHEDRON_MINIMUM } from "./SCREEN_PROBE.js";
+import { ScreenProbeDebugView } from "./ScreenProbeDebugView.js";
+
+/**
+ * Settings of {@link ShadeIndirectLightingMode.ScreenProbes}, held on `Renderer.screen_probes` and read every frame
+ * the mode runs. The world the probes trace and the world-space probes past their reach are the probe clipmap's,
+ * set by `Renderer.probe_clipmap` (`ProbeClipmapSettings`).
+ *
+ * Two kinds of field, by what a change costs:
+ * - **structure**: {@link downsample_factor} and {@link octahedron_resolution}. A change makes the screen probes'
+ *   resources again at the next frame, and their history starts from nothing.
+ * - **the rest** set the frame's passes and take effect the next frame without a rebuild.
+ *
+ * Each setter checks what its own value must be; what the device and the probes' layout hold is checked when the
+ * screen probes are made.
+ */
+export class ScreenProbeSettings {
+
+    #downsample_factor = 16;
+
+    /**
+     * Pixels between the uniform probes along each axis: one probe stands on the G-buffer in every square tile of
+     * this many pixels a side, Lumen's `ScreenProbeGather.DownsampleFactor`. Adaptive probes fill in between where
+     * interpolating the uniform ones would cross an edge ({@link adaptive_min_downsample_factor}). Every ray a probe
+     * casts and every pixel's interpolation scale with the count, so the cost goes as the inverse square of this.
+     * Structure.
+     * @returns {number}
+     */
+    get downsample_factor() {
+        return this.#downsample_factor;
+    }
+
+    /**
+     * @param {number} v a power of two from 1: tiles are found by shifts
+     */
+    set downsample_factor(v) {
+        assert.isPositiveInteger(v, 'downsample_factor');
+        assert.ok(isPowerOfTwo(v), 'downsample_factor must be a power of two');
+
+        this.#downsample_factor = v;
+    }
+
+    #octahedron_resolution = 8;
+
+    /**
+     * Texels a side of a probe's radiance, over the sphere by Clarberg's equal-area map: each probe casts this
+     * squared rays a frame, one a texel, Lumen's `TracingOctahedronResolution`. With importance sampling a ray may
+     * instead stand in a quarter of a texel at twice this resolution, where the probe's light is brightest.
+     * Structure.
+     * @returns {number}
+     */
+    get octahedron_resolution() {
+        return this.#octahedron_resolution;
+    }
+
+    /**
+     * @param {number} v 4, 8 or 16: Lumen's range, whose top is what a probe's workgroup sorts and accumulates in its
+     *   memory (`SCREEN_PROBE_OCTAHEDRON_MINIMUM`, `SCREEN_PROBE_OCTAHEDRON_LIMIT`)
+     */
+    set octahedron_resolution(v) {
+        assert.isPositiveInteger(v, 'octahedron_resolution');
+        assert.ok(isPowerOfTwo(v) && v >= SCREEN_PROBE_OCTAHEDRON_MINIMUM && v <= SCREEN_PROBE_OCTAHEDRON_LIMIT, 'octahedron_resolution must be 4, 8 or 16');
+
+        this.#octahedron_resolution = v;
+    }
+
+    #adaptive_min_downsample_factor = 4;
+
+    /**
+     * The finest spacing adaptive probes are placed at, in pixels, Lumen's `AdaptiveProbeMinDownsampleFactor`.
+     * Placement runs at half the {@link downsample_factor}, then a quarter, while the spacing is at least this:
+     * a pixel on that finer grid gets a probe where the probes already placed would not interpolate to it. At or
+     * above the downsample factor no adaptive probe is placed.
+     * @returns {number}
+     */
+    get adaptive_min_downsample_factor() {
+        return this.#adaptive_min_downsample_factor;
+    }
+
+    /**
+     * @param {number} v a power of two from 1
+     */
+    set adaptive_min_downsample_factor(v) {
+        assert.isPositiveInteger(v, 'adaptive_min_downsample_factor');
+        assert.ok(isPowerOfTwo(v), 'adaptive_min_downsample_factor must be a power of two');
+
+        this.#adaptive_min_downsample_factor = v;
+    }
+
+    #importance_sampling = true;
+
+    /**
+     * Whether a probe's rays follow where its light comes from (Lumen's structured importance sampling): each texel
+     * is weighed by the cosine lobes of the pixels around the probe and by the light the probe's history saw there;
+     * the rays of texels the pixels cannot see go, three at a time, to split the brightest texels into four. Off,
+     * every texel takes one ray. Takes effect the next frame.
+     * @returns {boolean}
+     */
+    get importance_sampling() {
+        return this.#importance_sampling;
+    }
+
+    /**
+     * @param {boolean} v
+     */
+    set importance_sampling(v) {
+        assert.isBoolean(v, 'importance_sampling');
+
+        this.#importance_sampling = v;
+    }
+
+    #screen_traces = true;
+
+    /**
+     * Whether a probe's rays are traced through the screen first, against the depth buffer's hierarchy, and lit by the
+     * last frame's colour where they hit; what the screen cannot answer goes on through the SDF bricks. Off, every
+     * ray is traced through the bricks alone. Takes effect the next frame.
+     * @returns {boolean}
+     */
+    get screen_traces() {
+        return this.#screen_traces;
+    }
+
+    /**
+     * @param {boolean} v
+     */
+    set screen_traces(v) {
+        assert.isBoolean(v, 'screen_traces');
+
+        this.#screen_traces = v;
+    }
+
+    #spatial_filter_passes = 3;
+
+    /**
+     * Passes of the filter between neighbouring probes, Lumen's `SpatialFilterNumPasses`: each texel takes its four
+     * neighbours' along the same direction where they stand on its surface and saw the same point. Zero records none.
+     * Takes effect the next frame.
+     * @returns {number}
+     */
+    get spatial_filter_passes() {
+        return this.#spatial_filter_passes;
+    }
+
+    /**
+     * @param {number} v a non-negative integer
+     */
+    set spatial_filter_passes(v) {
+        assert.isNonNegativeInteger(v, 'spatial_filter_passes');
+
+        this.#spatial_filter_passes = v;
+    }
+
+    #temporal_frames = 10;
+
+    /**
+     * The most frames the temporal filter averages a pixel's diffuse over, Lumen's `Temporal.MaxFramesAccumulated`:
+     * a pixel whose history holds blends its new light by 1 / (1 + frames). Where the probes' rays saw something
+     * move, it takes fewer. Takes effect the next frame.
+     * @returns {number}
+     */
+    get temporal_frames() {
+        return this.#temporal_frames;
+    }
+
+    /**
+     * @param {number} v frames, at least 1 and finite
+     */
+    set temporal_frames(v) {
+        assert.isFinite(v, 'temporal_frames');
+        assert.greaterThanOrEqual(v, 1, 'temporal_frames');
+
+        this.#temporal_frames = v;
+    }
+
+    #debug_view = ScreenProbeDebugView.None;
+
+    /**
+     * What the frame shows in place of its colour, before TAA: the frame itself, or one of the mode's debug views.
+     * Takes effect the next frame.
+     * @returns {ScreenProbeDebugView}
+     */
+    get debug_view() {
+        return this.#debug_view;
+    }
+
+    /**
+     * @param {ScreenProbeDebugView} v
+     */
+    set debug_view(v) {
+        assert.enum(v, ScreenProbeDebugView, 'debug_view');
+
+        this.#debug_view = v;
+    }
+}

package/src/shade/renderer/global_illumination/screen_probe/chunk_screen_probe.d.ts

@@ -0,0 +1,150 @@
+/**
+ * What every pass of a frame reads of the frame's probes, a uniform the host writes once a frame.
+ * @type {WebGPUStruct}
+ */
+export const SCREEN_PROBE_FRAME_STRUCT: WebGPUStruct;
+/**
+ * A screen probe, 32 bytes: where it stands on the G-buffer, as placement writes it.
+ * @type {WebGPUStruct}
+ */
+export const SCREEN_PROBE_STRUCT: WebGPUStruct;
+/**
+ * Where a screen probe's rays leave from in the bricks, where they end their trace and what answers for the rest,
+ * 64 bytes: the world-space probes picked at the probe (`probe_clipmap_pick`), its rays' origin, and its reach.
+ * @type {WebGPUStruct}
+ */
+export const SCREEN_PROBE_PICK_STRUCT: WebGPUStruct;
+/**
+ * A ray the screen left to the bricks, 28 bytes, through the passes that trace and light it.
+ * @type {WebGPUStruct}
+ */
+export const SCREEN_PROBE_RAY_STRUCT: WebGPUStruct;
+/** @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_FRAME_RESOURCE: ShaderResourceDescriptor;
+/**
+ * The factor the display multiplies radiance by ahead of its tone curve, as the last frame was shown: what the
+ * probes' radiance is pre-exposed by, Lumen's `View.PreExposure`.
+ * @type {ShaderResourceDescriptor}
+ */
+export const SCREEN_PROBE_EXPOSURE_RESOURCE: ShaderResourceDescriptor;
+/** The exposure last frame's probes' radiance was pre-exposed by. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_EXPOSURE_PREVIOUS_RESOURCE: ShaderResourceDescriptor;
+/** The frame's probes, uniform then adaptive. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBES_READ_RESOURCE: ShaderResourceDescriptor;
+/** @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBES_WRITE_RESOURCE: ShaderResourceDescriptor;
+/** Last frame's probes, as this frame's lighting density reprojects into. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBES_PREVIOUS_RESOURCE: ShaderResourceDescriptor;
+/** @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_PICKS_READ_RESOURCE: ShaderResourceDescriptor;
+/** @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_PICKS_WRITE_RESOURCE: ShaderResourceDescriptor;
+/** The commands and counts of the frame (`SCREEN_PROBE_DISPATCH_*`), read-only to the passes after the one that writes them. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_DISPATCH_READ_RESOURCE: ShaderResourceDescriptor;
+/** @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_DISPATCH_WRITE_RESOURCE: ShaderResourceDescriptor;
+/** The frame's atomic counters (`SCREEN_PROBE_COUNTER_*`). @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_COUNTERS_RESOURCE: ShaderResourceDescriptor;
+/** @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_COUNTERS_READ_RESOURCE: ShaderResourceDescriptor;
+/** Each tile's count of adaptive probes. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_TILE_COUNTS_READ_RESOURCE: ShaderResourceDescriptor;
+/** @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_TILE_COUNTS_WRITE_RESOURCE: ShaderResourceDescriptor;
+/** Each tile's adaptive probes, `adaptive_tile_capacity` slots a tile: the k of probe uniform_count + k. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_TILE_PROBES_READ_RESOURCE: ShaderResourceDescriptor;
+/** @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_TILE_PROBES_WRITE_RESOURCE: ShaderResourceDescriptor;
+/** The rays the screen left to the bricks. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_RAYS_READ_RESOURCE: ShaderResourceDescriptor;
+/** @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_RAYS_WRITE_RESOURCE: ShaderResourceDescriptor;
+/** Each probe's share of its rays' light that came from something moving relative to it, 0 to 1, as the composite writes it. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_MOVING_READ_RESOURCE: ShaderResourceDescriptor;
+/** @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_MOVING_WRITE_RESOURCE: ShaderResourceDescriptor;
+/** Each probe's radiance, `rgba16float`, n² texels a probe in the atlas: rgb the radiance pre-exposed (`screen_probe_exposure`), a the nearest hit of the rays it holds, negative where none landed. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_RADIANCE_READ_RESOURCE: ShaderResourceDescriptor;
+/** @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_RADIANCE_WRITE_RESOURCE: ShaderResourceDescriptor;
+/** Each probe's pre-exposed radiance SH3, as the probe clipmap's records hold theirs (`probe_record_sh_encode`). @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_SH_READ_RESOURCE: ShaderResourceDescriptor;
+/** @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_SH_WRITE_RESOURCE: ShaderResourceDescriptor;
+/** Each ray's texel and level, `r32uint`, a texel a ray in the probes' atlas. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_RAY_INFO_READ_RESOURCE: ShaderResourceDescriptor;
+/** @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_RAY_INFO_WRITE_RESOURCE: ShaderResourceDescriptor;
+/** Each ray's radiance pre-exposed (`screen_probe_exposure`), `rgba16float`. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_TRACE_RADIANCE_READ_RESOURCE: ShaderResourceDescriptor;
+/** @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_TRACE_RADIANCE_WRITE_RESOURCE: ShaderResourceDescriptor;
+/** Each ray's hit word (`screen_probe_trace_hit_pack`), `r32uint`. @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_TRACE_HIT_READ_RESOURCE: ShaderResourceDescriptor;
+/** @type {ShaderResourceDescriptor} */
+export const SCREEN_PROBE_TRACE_HIT_WRITE_RESOURCE: ShaderResourceDescriptor;
+/**
+ * Probe addressing, the probes' records and their rays' words (Lumen's `LumenScreenProbeCommon.ush`):
+ *
+ * ```wgsl
+ * fn screen_probe_atlas(probe: u32) -> vec2<u32>                    // the probe's place in the atlas, in probes
+ * fn screen_probe_texel(probe: u32, slot: u32) -> vec2<u32>          // its slot's texel in an atlas of n² a probe
+ * fn screen_probe_pixel_encode(pixel: vec2<u32>) -> u32
+ * fn screen_probe_pixel_decode(word: u32) -> vec2<u32>
+ * fn screen_probe_tile_of_pixel(pixel: vec2<u32>) -> vec2<u32>       // the tile of a pixel placed on this frame's grid
+ * fn screen_probe_plane_weight(plane: vec4<f32>, point: vec3<f32>, depth: f32) -> f32
+ * fn screen_probe_ray_info_pack(texel: vec2<u32>, level: u32) -> u32
+ * fn screen_probe_ray_info_texel(info: u32) -> vec2<u32>
+ * fn screen_probe_ray_info_level(info: u32) -> u32                   // 1 the probe's n, 0 twice it
+ * fn screen_probe_ray_direction(info: u32, jitter: vec2<f32>) -> vec3<f32>
+ * fn screen_probe_trace_hit_pack(kind: u32, distance: f32, moving: bool) -> u32
+ * fn screen_probe_trace_hit_kind(word: u32) -> u32
+ * fn screen_probe_trace_hit_distance(word: u32) -> f32
+ * fn screen_probe_texel_wrap(texel: vec2<i32>) -> vec2<u32>         // a texel a step outside the octahedron, folded in
+ * ```
+ *
+ * - **The atlas**: probe i at (i mod tile_count.x, i div tile_count.x), the uniform probes on their tiles and the
+ *   adaptive ones in the rows below, a probe's n² texels at n times its place in every per-ray and per-texel texture.
+ * - **The plane weight**: `exp2(−k·(|n·p − d| / depth)²)`, `SCREEN_PROBE_PLANE_WEIGHT_SCALE`, the distance of a point
+ *   from a receiver's plane over the receiver's depth: Lumen's, with the face normal's plane where Lumen takes the
+ *   shading normal's, so a normal map does not part probes on one flat surface.
+ * - **A ray's info**: the texel at its level's resolution, 2n at level 0 and n at level 1, and the level.
+ * - **A ray's direction**: Clarberg's equal-area map at its texel plus the probe's jitter over the level's resolution,
+ *   so a probe's texels all hold the same solid angle, 4π/n², and a child a quarter of it.
+ * - **A hit word**: the kind (`SCREEN_PROBE_TRACE_*`) and moving bit low, the distance as a half float high.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_screen_probe: CodeChunk;
+/**
+ * Where in its texel each of a probe's rays falls this frame, the same for every texel of the probe:
+ *
+ * ```wgsl
+ * fn screen_probe_noise_tile(probe: u32, pixel: vec2<u32>) -> vec2<u32>   // the tile whose noise a probe draws
+ * fn screen_probe_ray_jitter(tile: vec2<u32>) -> vec2<f32>
+ * ```
+ *
+ * The spatio-temporal blue noise at the probe's tile and the frame (Lumen's per-tile blue noise), shared by the
+ * tile's probes: neighbouring probes' jitters are spread apart, and a probe's spread over the frames the temporal
+ * filter averages. A uniform probe's tile is its place in the atlas; an adaptive probe's, the tile its pixel stands
+ * in (`pixel`, its record's), as Lumen keys a probe's noise by its screen tile. Every pass that places a probe's
+ * rays or reads them back by direction takes the tile from here.
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_screen_probe_ray_jitter: CodeChunk;
+/**
+ * The frame's counts, from the pass that writes the commands:
+ *
+ * ```wgsl
+ * fn screen_probe_count() -> u32        // the frame's probes, uniform and adaptive
+ * fn screen_probe_brick_ray_count() -> u32 // the rays the screen left to the bricks, held to their list's slots
+ * ```
+ *
+ * @type {CodeChunk}
+ */
+export const chunk_screen_probe_counts: CodeChunk;
+import { WebGPUStruct } from "../../shader/type/WebGPUStruct.js";
+import { ShaderResourceDescriptor } from "../../shader/resource/ShaderResourceDescriptor.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+//# sourceMappingURL=chunk_screen_probe.d.ts.map

package/src/shade/renderer/global_illumination/screen_probe/chunk_screen_probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunk_screen_probe.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/global_illumination/screen_probe/chunk_screen_probe.js"],"names":[],"mappings":"AA2BA;;;GAGG;AACH,wCAFU,YAAY,CA2CC;AAEvB;;;GAGG;AACH,kCAFU,YAAY,CAaJ;AAElB;;;;GAIG;AACH,uCAFU,YAAY,CAgBA;AAEtB;;;GAGG;AACH,sCAFU,YAAY,CAiBD;AAErB,uCAAuC;AACvC,0CADW,wBAAwB,CAC0F;AAE7H;;;;GAIG;AACH,6CAFU,wBAAwB,CAE4F;AAE9H,sGAAsG;AACtG,sDAD0E,wBAAwB,CAC8C;AAEhJ,kFAAkF;AAClF,0CADsD,wBAAwB,CAC4D;AAC1I,uCAAuC;AACvC,2CADW,wBAAwB,CAC8G;AAEjJ,8GAA8G;AAC9G,8CADkF,wBAAwB,CAC6C;AAEvJ,uCAAuC;AACvC,+CADW,wBAAwB,CACsH;AACzJ,uCAAuC;AACvC,gDADW,wBAAwB,CAC6H;AAEhK,iKAAiK;AACjK,kDADqI,wBAAwB,CACzB;AACpI,uCAAuC;AACvC,mDADW,wBAAwB,CACwG;AAE3I,+FAA+F;AAC/F,6CADmE,wBAAwB,CACuD;AAClJ,uCAAuC;AACvC,kDADW,wBAAwB,CACiG;AAEpI,6EAA6E;AAC7E,qDADiD,wBAAwB,CACiE;AAC1I,uCAAuC;AACvC,sDADW,wBAAwB,CAC2H;AAE9J,6IAA6I;AAC7I,qDADiH,wBAAwB,CACC;AAC1I,uCAAuC;AACvC,sDADW,wBAAwB,CAC8G;AAEjJ,+EAA+E;AAC/E,8CADmD,wBAAwB,CAC2E;AACtJ,uCAAuC;AACvC,+CADW,wBAAwB,CAC0H;AAE7J,iKAAiK;AACjK,gDADqI,wBAAwB,CACvB;AACtI,uCAAuC;AACvC,iDADW,wBAAwB,CAC0G;AAE7I,yOAAyO;AACzO,kDAD6M,wBAAwB,CAClG;AACnI,uCAAuC;AACvC,mDADW,wBAAwB,CACyH;AAE5J,qJAAqJ;AACrJ,4CADyH,wBAAwB,CACzB;AACxH,uCAAuC;AACvC,6CADW,wBAAwB,CAC4F;AAE/H,kHAAkH;AAClH,kDADsF,wBAAwB,CACO;AACrH,uCAAuC;AACvC,mDADW,wBAAwB,CACiH;AAEpJ,iHAAiH;AACjH,wDADqF,wBAAwB,CACkC;AAC/I,uCAAuC;AACvC,yDADW,wBAAwB,CACiI;AAEpK,uGAAuG;AACvG,mDAD2E,wBAAwB,CACoB;AACvH,uCAAuC;AACvC,oDADW,wBAAwB,CACmH;AAEtJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,iCAFU,SAAS,CAwGZ;AAIP;;;;;;;;;;;;;;;GAeG;AACH,4CAFU,SAAS,CAeZ;AAIP;;;;;;;;;GASG;AACH,wCAFU,SAAS,CAYhB;6BA7Y0B,mCAAmC;yCAJvB,mDAAmD;0BADlE,oCAAoC"}