@woosh/meep-engine 3.1.0 → 3.2.0

package/src/shade/renderer/postprocess/motion_blur/MotionBlur.js

@@ -1,56 +1,56 @@
-import { graph_postprocess_motion_blur } from "./graph_postprocess_motion_blur.js";
-
-/**
- * Jimenez 2014 reconstruction-filter motion blur as a self-contained
- * post-effect manager — the same pattern as {@link DepthOfField} /
- * {@link GPUCameraExposureManager}. The Renderer holds one and exposes it
- * as `renderer.motion_blur`; the `feature_motion_blur_enabled` toggle stays
- * on the Renderer (a peer of the other `feature_*` flags). Everything else
- * (currently just {@link strength}) lives here, off the Renderer.
- *
- * Unlike DoF / auto-exposure this owns no GPU resources: the three image
- * passes are transient frame-graph nodes rebuilt each {@link render}, so
- * there's nothing to construct with a device and nothing to destroy. See
- * {@link graph_postprocess_motion_blur} for the algorithm.
- */
-export class MotionBlur {
-    /**
-     * Velocity scale applied uniformly inside the motion-blur
-     * reconstruction. `1.0` is physical (matches the real per-frame
-     * pixel displacement), which at 60–120 fps yields a deliberately
-     * subtle blur — each frame only integrates a few ms of motion.
-     * Higher values approximate a "longer shutter": `2.0`–`3.0`
-     * lands in cinematic (180° shutter on 24 fps source) territory.
-     *
-     * @type {number}
-     */
-    strength = 1.0;
-
-    /**
-     * Run the motion-blur reconstruction and return the new colour handle.
-     *
-     * Designed to run on the resolved-but-not-sharpened HDR colour: TAA has
-     * already converged the jittered samples, and sharpening / bloom /
-     * tonemap operate on the blurred output after this. The caller gates on
-     * {@link Renderer#feature_motion_blur_enabled} so the rest of the chain
-     * stays bit-identical when the effect is off.
-     *
-     * @param {object} args
-     * @param {FrameGraph} args.graph
-     * @param {number} args.input_color  FrameGraph handle, rgba16float HDR colour (post-TAA)
-     * @param {number} args.velocity     FrameGraph handle, rg16float pixel-space velocity
-     * @param {number} args.depth        FrameGraph handle, depth texture
-     * @param {number[]} args.resolution full output resolution `[w, h]`
-     * @returns {number} FrameGraph handle to the motion-blurred colour
-     */
-    render({ graph, input_color, velocity, depth, resolution }) {
-        return graph_postprocess_motion_blur({
-            graph,
-            input_color,
-            velocity,
-            depth,
-            resolution,
-            strength: this.strength,
-        });
-    }
-}
+import { graph_postprocess_motion_blur } from "./graph_postprocess_motion_blur.js";
+
+/**
+ * Jimenez 2014 reconstruction-filter motion blur as a self-contained
+ * post-effect manager — the same pattern as {@link DepthOfField} /
+ * {@link GPUCameraExposureManager}. The Renderer holds one and exposes it
+ * as `renderer.motion_blur`; the `feature_motion_blur_enabled` toggle stays
+ * on the Renderer (a peer of the other `feature_*` flags). Everything else
+ * (currently just {@link strength}) lives here, off the Renderer.
+ *
+ * Unlike DoF / auto-exposure this owns no GPU resources: the three image
+ * passes are transient frame-graph nodes rebuilt each {@link render}, so
+ * there's nothing to construct with a device and nothing to destroy. See
+ * {@link graph_postprocess_motion_blur} for the algorithm.
+ */
+export class MotionBlur {
+    /**
+     * Velocity scale applied uniformly inside the motion-blur
+     * reconstruction. `1.0` is physical (matches the real per-frame
+     * pixel displacement), which at 60–120 fps yields a deliberately
+     * subtle blur — each frame only integrates a few ms of motion.
+     * Higher values approximate a "longer shutter": `2.0`–`3.0`
+     * lands in cinematic (180° shutter on 24 fps source) territory.
+     *
+     * @type {number}
+     */
+    strength = 1.0;
+
+    /**
+     * Run the motion-blur reconstruction and return the new colour handle.
+     *
+     * Designed to run on the resolved-but-not-sharpened HDR colour: TAA has
+     * already converged the jittered samples, and sharpening / bloom /
+     * tonemap operate on the blurred output after this. The caller gates on
+     * {@link Renderer#feature_motion_blur_enabled} so the rest of the chain
+     * stays bit-identical when the effect is off.
+     *
+     * @param {object} args
+     * @param {FrameGraph} args.graph
+     * @param {number} args.input_color  FrameGraph handle, rgba16float HDR colour (post-TAA)
+     * @param {number} args.velocity     FrameGraph handle, rg16float pixel-space velocity
+     * @param {number} args.depth        FrameGraph handle, depth texture
+     * @param {number[]} args.resolution full output resolution `[w, h]`
+     * @returns {number} FrameGraph handle to the motion-blurred colour
+     */
+    render({ graph, input_color, velocity, depth, resolution }) {
+        return graph_postprocess_motion_blur({
+            graph,
+            input_color,
+            velocity,
+            depth,
+            resolution,
+            strength: this.strength,
+        });
+    }
+}

package/src/shade/renderer/postprocess/upscale-dither/NOTES.md

@@ -1,78 +1,78 @@
-# Dithered Bilateral Upscale
-
-Depth-aware upscale for low-resolution screen-space effects (volumetric
-lighting / fog, GTAO, soft shadows, etc.). Reconstructs a full-resolution
-image by weighting low-res neighbours by depth similarity, with a per-pixel
-noise-driven tap rotation so the reconstruction error becomes high-frequency
-dither instead of coherent banding.
-
-## Algorithm
-
-Per full-resolution pixel:
-
-1. Linearise the full-res device depth to view-space Z via
-   `chunk_get_view_space_depth`.
-2. Draw a per-pixel blue-noise angle from `HILBERT_R2_INDEX_TEXTURE` using
-   `chunk_spatio_temporal_noise_r2_64`.
-3. Sample 4 low-res taps arranged on a unit square rotated by that angle
-   around the full-res pixel's position expressed in low-res texel space.
-4. Weight each tap by `exp(-|z_tap - z_full| / depth_phi)`
-   (`chunk_depth_edge_stopping_weight`, reused from the SVGF denoiser).
-5. Return the weighted average. If the accumulated weight falls below a
-   small epsilon (every tap failed the depth test), fall back to the tap
-   with the smallest depth delta.
-
-## Inputs the caller must provide
-
-- **Low-res color** - whatever the upscaler is reconstructing
-  (HDR `rgba16float` for volumetrics, `rg16float` moments for GTAO, etc.).
-- **Low-res depth** - view-space (linear) Z at the low-res sample positions.
-  Ideally produced alongside the low-res effect: a raymarching volumetric
-  shader already knows its sample depth, and a dedicated min/max depth
-  downsample shader works for effects that do not. Storing linear Z
-  (not device Z) avoids re-linearising on every tap.
-- **Full-res depth** - the renderer's regular device-space G-buffer depth.
-
-## Expected output format
-
-The default `shader_upscale_dither` writes `rgba16float`. For non-HDR targets
-construct a fresh `ImageShader` from `fragment_shader_upscale_dither` with
-the format you need.
-
-## `depth_phi` tuning
-
-`depth_phi` is the bilateral tolerance in view-space meters. Typical values:
-
-| Effect                  | `depth_phi` |
-|-------------------------|-------------|
-| Volumetric fog (soft)   | 1.0 - 5.0   |
-| GTAO / contact shadows  | 0.1 - 0.5   |
-
-Smaller = stricter depth matching, sharper silhouettes, more fallback hits.
-Larger = softer, risks light leaks across depth edges.
-
-## What this pass does **not** do
-
-- No normal-aware weighting. The original RDR2 variant is depth-only;
-  add normal edge-stopping (see `chunk_normal_edge_stopping_weight`) if a
-  future effect needs it and you have a matching low-res normal buffer.
-- No TAA / temporal accumulation. Pair with the existing TAA pass if the
-  single-frame dither is too visible.
-- No downsample helper. Callers either render the effect at low-res
-  natively (which produces the matching depth for free) or run a dedicated
-  depth downsample pass first.
-
-## References
-
-- Fabian Bauer, *Creating the Atmospheric World of Red Dead Redemption 2:
-  A Complete and Integrated Solution*, SIGGRAPH 2019 Advances in Real-Time
-  Rendering. https://advances.realtimerendering.com/s2019/
-- Angelo Pesce (c0de517e), *Low-resolution effects with depth-aware
-  upsampling*.
-  https://c0de517e.blogspot.com/2016/02/downsampled-effects-with-depth-aware.html
-- pixelmager, depth-aware upsampling gist (summarises the RDR2 variant and
-  its three iterations).
-  https://gist.github.com/pixelmager/a4364ea18305ed5ca707d89ddc5f8743
-- Bart Wronski, *Volumetric Fog* (SIGGRAPH 2014) - earlier prior art on
-  the same family of bilateral-upsample techniques.
-  https://bartwronski.com/wp-content/uploads/2014/08/bwronski_volumetric_fog_siggraph2014.pdf
+# Dithered Bilateral Upscale
+
+Depth-aware upscale for low-resolution screen-space effects (volumetric
+lighting / fog, GTAO, soft shadows, etc.). Reconstructs a full-resolution
+image by weighting low-res neighbours by depth similarity, with a per-pixel
+noise-driven tap rotation so the reconstruction error becomes high-frequency
+dither instead of coherent banding.
+
+## Algorithm
+
+Per full-resolution pixel:
+
+1. Linearise the full-res device depth to view-space Z via
+   `chunk_get_view_space_depth`.
+2. Draw a per-pixel blue-noise angle from `HILBERT_R2_INDEX_TEXTURE` using
+   `chunk_spatio_temporal_noise_r2_64`.
+3. Sample 4 low-res taps arranged on a unit square rotated by that angle
+   around the full-res pixel's position expressed in low-res texel space.
+4. Weight each tap by `exp(-|z_tap - z_full| / depth_phi)`
+   (`chunk_depth_edge_stopping_weight`, reused from the SVGF denoiser).
+5. Return the weighted average. If the accumulated weight falls below a
+   small epsilon (every tap failed the depth test), fall back to the tap
+   with the smallest depth delta.
+
+## Inputs the caller must provide
+
+- **Low-res color** - whatever the upscaler is reconstructing
+  (HDR `rgba16float` for volumetrics, `rg16float` moments for GTAO, etc.).
+- **Low-res depth** - view-space (linear) Z at the low-res sample positions.
+  Ideally produced alongside the low-res effect: a raymarching volumetric
+  shader already knows its sample depth, and a dedicated min/max depth
+  downsample shader works for effects that do not. Storing linear Z
+  (not device Z) avoids re-linearising on every tap.
+- **Full-res depth** - the renderer's regular device-space G-buffer depth.
+
+## Expected output format
+
+The default `shader_upscale_dither` writes `rgba16float`. For non-HDR targets
+construct a fresh `ImageShader` from `fragment_shader_upscale_dither` with
+the format you need.
+
+## `depth_phi` tuning
+
+`depth_phi` is the bilateral tolerance in view-space meters. Typical values:
+
+| Effect                  | `depth_phi` |
+|-------------------------|-------------|
+| Volumetric fog (soft)   | 1.0 - 5.0   |
+| GTAO / contact shadows  | 0.1 - 0.5   |
+
+Smaller = stricter depth matching, sharper silhouettes, more fallback hits.
+Larger = softer, risks light leaks across depth edges.
+
+## What this pass does **not** do
+
+- No normal-aware weighting. The original RDR2 variant is depth-only;
+  add normal edge-stopping (see `chunk_normal_edge_stopping_weight`) if a
+  future effect needs it and you have a matching low-res normal buffer.
+- No TAA / temporal accumulation. Pair with the existing TAA pass if the
+  single-frame dither is too visible.
+- No downsample helper. Callers either render the effect at low-res
+  natively (which produces the matching depth for free) or run a dedicated
+  depth downsample pass first.
+
+## References
+
+- Fabian Bauer, *Creating the Atmospheric World of Red Dead Redemption 2:
+  A Complete and Integrated Solution*, SIGGRAPH 2019 Advances in Real-Time
+  Rendering. https://advances.realtimerendering.com/s2019/
+- Angelo Pesce (c0de517e), *Low-resolution effects with depth-aware
+  upsampling*.
+  https://c0de517e.blogspot.com/2016/02/downsampled-effects-with-depth-aware.html
+- pixelmager, depth-aware upsampling gist (summarises the RDR2 variant and
+  its three iterations).
+  https://gist.github.com/pixelmager/a4364ea18305ed5ca707d89ddc5f8743
+- Bart Wronski, *Volumetric Fog* (SIGGRAPH 2014) - earlier prior art on
+  the same family of bilateral-upsample techniques.
+  https://bartwronski.com/wp-content/uploads/2014/08/bwronski_volumetric_fog_siggraph2014.pdf

package/src/shade/renderer/postprocess/upscale-dither/UpscaleDither.js

@@ -1,95 +1,95 @@
-import { graph_image_pass } from "../../shader/graph/graph_image_pass.js";
-import { shader_upscale_dither } from "./fragment_shader_upscale_dither.js";
-
-/**
- * Dithered bilateral upscale pass - reconstructs a full-resolution image from
- * a low-resolution color buffer plus a matching low-resolution view-space
- * depth buffer, guided by the full-resolution device depth.
- *
- * Intended use: upscaling low-res effects like volumetric lighting or GTAO
- * into the main render resolution without bilateral halos around silhouettes.
- *
- * The upscale shader itself is stateless; this class is a thin wrapper so
- * the pass slots into the same `PostProcess` / `graph_pass` convention used
- * by {@link GTAO}, {@link SSR}, etc.
- *
- * See {@link fragment_shader_upscale_dither} for the full algorithm.
- *
- * References:
- * - Fabian Bauer, "Creating the Atmospheric World of Red Dead Redemption 2:
- *   A Complete and Integrated Solution", SIGGRAPH 2019 Advances in Real-Time
- *   Rendering. https://advances.realtimerendering.com/s2019/
- * - Angelo Pesce (c0de517e), "Low-resolution effects with depth-aware
- *   upsampling".
- *   https://c0de517e.blogspot.com/2016/02/downsampled-effects-with-depth-aware.html
- * - pixelmager, depth-aware upsampling gist (summarises the RDR2 variant
- *   and its three iterations).
- *   https://gist.github.com/pixelmager/a4364ea18305ed5ca707d89ddc5f8743
- * - Bart Wronski, "Volumetric Fog" (SIGGRAPH 2014) - earlier prior art on
- *   the same family of bilateral-upsample techniques.
- *   https://bartwronski.com/wp-content/uploads/2014/08/bwronski_volumetric_fog_siggraph2014.pdf
- */
-export class UpscaleDither {
-
-    /**
-     * @param {GraphicsContext} graphics
-     */
-    constructor(graphics) {
-        // Stateless pass - nothing to allocate. Constructor kept for API
-        // parity with other postprocess classes.
-    }
-
-    /**
-     * Queue a dithered upscale pass into the render graph.
-     *
-     * @param {FrameGraph} graph
-     * @param {number} camera       Camera uniform buffer (CAMERA_UNIFORM_STRUCT).
-     * @param {number} input_color  Low-resolution color texture to upscale.
-     * @param {number} input_depth_low View-space (linear) Z at the low-res sample positions.
-     * @param {number} input_depth_full Full-resolution device-space depth (G-buffer depth).
-     * @param {number} frame_index  Frame counter; drives the dither pattern.
-     * @param {number[]} resolution Full-res output resolution `[width, height]`.
-     * @param {number} [depth_phi]  Bilateral depth tolerance in view-space units.
-     *                              Larger values accept more distant samples.
-     * @param {number} [output]     Optional pre-allocated output texture. If
-     *                              omitted, the graph allocates one.
-     * @returns {number} Graph resource id of the upscaled full-res color.
-     */
-    graph_pass({
-                   graph,
-                   camera,
-                   input_color,
-                   input_depth_low,
-                   input_depth_full,
-                   frame_index,
-                   resolution,
-                   depth_phi = 1.0,
-                   output,
-               }) {
-
-        const pass_args = {
-            graph,
-            shader: shader_upscale_dither,
-            inputs: {
-                tInput: input_color,
-                tInputDepth: input_depth_low,
-                tDepth: input_depth_full,
-                camera,
-                settings: {
-                    frame_index,
-                    depth_phi,
-                },
-            },
-        };
-
-        if (output !== undefined) {
-            pass_args.output = [output];
-        } else {
-            pass_args.output_resolution = resolution;
-        }
-
-        const [upscaled] = graph_image_pass(pass_args);
-
-        return upscaled;
-    }
-}
+import { graph_image_pass } from "../../shader/graph/graph_image_pass.js";
+import { shader_upscale_dither } from "./fragment_shader_upscale_dither.js";
+
+/**
+ * Dithered bilateral upscale pass - reconstructs a full-resolution image from
+ * a low-resolution color buffer plus a matching low-resolution view-space
+ * depth buffer, guided by the full-resolution device depth.
+ *
+ * Intended use: upscaling low-res effects like volumetric lighting or GTAO
+ * into the main render resolution without bilateral halos around silhouettes.
+ *
+ * The upscale shader itself is stateless; this class is a thin wrapper so
+ * the pass slots into the same `PostProcess` / `graph_pass` convention used
+ * by {@link GTAO}, {@link SSR}, etc.
+ *
+ * See {@link fragment_shader_upscale_dither} for the full algorithm.
+ *
+ * References:
+ * - Fabian Bauer, "Creating the Atmospheric World of Red Dead Redemption 2:
+ *   A Complete and Integrated Solution", SIGGRAPH 2019 Advances in Real-Time
+ *   Rendering. https://advances.realtimerendering.com/s2019/
+ * - Angelo Pesce (c0de517e), "Low-resolution effects with depth-aware
+ *   upsampling".
+ *   https://c0de517e.blogspot.com/2016/02/downsampled-effects-with-depth-aware.html
+ * - pixelmager, depth-aware upsampling gist (summarises the RDR2 variant
+ *   and its three iterations).
+ *   https://gist.github.com/pixelmager/a4364ea18305ed5ca707d89ddc5f8743
+ * - Bart Wronski, "Volumetric Fog" (SIGGRAPH 2014) - earlier prior art on
+ *   the same family of bilateral-upsample techniques.
+ *   https://bartwronski.com/wp-content/uploads/2014/08/bwronski_volumetric_fog_siggraph2014.pdf
+ */
+export class UpscaleDither {
+
+    /**
+     * @param {GraphicsContext} graphics
+     */
+    constructor(graphics) {
+        // Stateless pass - nothing to allocate. Constructor kept for API
+        // parity with other postprocess classes.
+    }
+
+    /**
+     * Queue a dithered upscale pass into the render graph.
+     *
+     * @param {FrameGraph} graph
+     * @param {number} camera       Camera uniform buffer (CAMERA_UNIFORM_STRUCT).
+     * @param {number} input_color  Low-resolution color texture to upscale.
+     * @param {number} input_depth_low View-space (linear) Z at the low-res sample positions.
+     * @param {number} input_depth_full Full-resolution device-space depth (G-buffer depth).
+     * @param {number} frame_index  Frame counter; drives the dither pattern.
+     * @param {number[]} resolution Full-res output resolution `[width, height]`.
+     * @param {number} [depth_phi]  Bilateral depth tolerance in view-space units.
+     *                              Larger values accept more distant samples.
+     * @param {number} [output]     Optional pre-allocated output texture. If
+     *                              omitted, the graph allocates one.
+     * @returns {number} Graph resource id of the upscaled full-res color.
+     */
+    graph_pass({
+                   graph,
+                   camera,
+                   input_color,
+                   input_depth_low,
+                   input_depth_full,
+                   frame_index,
+                   resolution,
+                   depth_phi = 1.0,
+                   output,
+               }) {
+
+        const pass_args = {
+            graph,
+            shader: shader_upscale_dither,
+            inputs: {
+                tInput: input_color,
+                tInputDepth: input_depth_low,
+                tDepth: input_depth_full,
+                camera,
+                settings: {
+                    frame_index,
+                    depth_phi,
+                },
+            },
+        };
+
+        if (output !== undefined) {
+            pass_args.output = [output];
+        } else {
+            pass_args.output_resolution = resolution;
+        }
+
+        const [upscaled] = graph_image_pass(pass_args);
+
+        return upscaled;
+    }
+}