@woosh/meep-engine 3.60.1 → 3.60.3

package/package.json

@@ -6,7 +6,7 @@
   "description": "Advanced 3D game engine",
   "type": "module",
   "author": "Alexander Goldring",
-  "version": "3.60.1",
+  "version": "3.60.3",
   "exports": {
     "./build/*": "./build/*",
     "./src/*": "./src/*",

package/src/shade/playground/sh_exponential/main.js

@@ -1,7 +1,7 @@
 import { ShadeGPUCommandContext } from "../../device/ShadeGPUCommandContext.js";
 import { GPUFrameRecorder } from "../../device/timing/profile/GPUFrameRecorder.js";
 import { GraphicsContext } from "../../renderer/GraphicsContext.js";
-import { execute_filter_environment_map } from "../../renderer/light/environment/execute_filter_environment_map.js";
+import { encode_filter_environment_map } from "../../renderer/light/environment/graph_filter_environment_map.js";
 import { load_environment_map, ProjectionMappingType } from "../../renderer/light/environment/rgbe/load_environment_map.js";
 import { SH_EXP_ENCODE_PARAMETERS_STRUCT } from "../../renderer/light/environment/sh_exponential/SH_EXP_ENCODE_PARAMETERS_STRUCT.js";
 import { SH_EXP_P4Q2_SETTINGS, SHExpEncoder } from "../../renderer/light/environment/sh_exponential/SHExpEncoder.js";
@@ -289,7 +289,7 @@ async function main() {
         const cmd = ShadeGPUCommandContext.create(graphics, 'SH exponential playground / environment');
 
         // the engine IBL row reads the prefiltered levels, exactly as the forward path does
-        execute_filter_environment_map(environment, cmd);
+        encode_filter_environment_map(environment, cmd);
 
         // the reference's own grid, finer than the encoder's
         shader_sh_exp_environment_cells.dispatch({

package/src/shade/renderer/global_illumination/probe_clipmap/PROBE_CLIPMAP_PROPOSAL_2026_10_27.md

@@ -3230,6 +3230,10 @@ a per-invocation function instead. Each is tier 2 whole, and no thread's loop ru
    - one bilinear depth tap toward p_b at distance `|p_b − probe|/s_c`;
    - weight = trilinear × `probe_visibility_weight`: the wrap back face, Chebyshev from the tap, and
      the crush.
+   - The wrap is `((n·ω+1)/2)²`, without DDGI's + 0.2. With it, a probe behind Sponza's thin outer
+     wall, which Chebyshev passes at 0.94–0.97 through the grazing texels of an 8² depth map, held ≈0.25,
+     above the crush: 11% of the wall's pick, 32% in cascade 1, where the wall sits 0.15 of a spacing past
+     the lattice plane, a dark lattice of blotches. Without it, 0.1% and 0.6%.
 
    No SH and no radiance is read here.
 4. **Pick two**, the extracted `pick2_wrs_mat2x4`, which is Brick4's selection:

package/src/shade/renderer/light/GPULightCollection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GPULightCollection.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/light/GPULightCollection.js"],"names":[],"mappings":"AAsDA;IAEI;;;;;OAKG;IACH,iCAFW,eAAe,QAOzB;IA6KD;;;;;;OAMG;IACH,sBALW,eAAe,aACf,eAAe,EA2CzB;IAnND;;;OAGG;IACH,6DAEC;IAeD;;OAEG;IACH,4BAEC;IAED;;;;;;OAMG;IACH,6BAEC;IAED;;;;;;;OAOG;IACH,qFAEC;IAWD;;OAEG;IACH,+CAEC;IA6DD;;;OAGG;IACH,qCAEC;IAED;;;;;;OAMG;IACH,gCAEC;IAED;;;;;;OAMG;IACH,yCAEC;IAGD,4BAMC;IAoMD;;;OAGG;IACH,YAFW,eAAe,QAoCzB;IAED;;;;;;;;;OASG;IACH,gBAFW,OAAO,+BAA+B,EAAE,YAAY,QAkC9D;IAED;;;;;;OAMG;IACH,uBAHW,sBAAsB,mCA6BhC;IAwED,gBAUC;;CACJ;8BA1lBY,OAAO,0CAA0C,EAAE,eAAe;8BAClE,OAAO,uBAAuB,EAAE,eAAe;8BAC/C,OAAO,6BAA6B,EAAE,eAAe;8BACrD,OAAO,sBAAsB,EAAE,eAAe;4BA/B/B,gCAAgC;yCACnB,2CAA2C;kCAClD,iCAAiC;uCAH5B,wCAAwC"}
+{"version":3,"file":"GPULightCollection.d.ts","sourceRoot":"","sources":["../../../../../src/shade/renderer/light/GPULightCollection.js"],"names":[],"mappings":"AAoDA;IAEI;;;;;OAKG;IACH,iCAFW,eAAe,QAOzB;IA6KD;;;;;;OAMG;IACH,sBALW,eAAe,aACf,eAAe,EA2CzB;IAnND;;;OAGG;IACH,6DAEC;IAeD;;OAEG;IACH,4BAEC;IAED;;;;;;OAMG;IACH,6BAEC;IAED;;;;;;;OAOG;IACH,qFAEC;IAWD;;OAEG;IACH,+CAEC;IA6DD;;;OAGG;IACH,qCAEC;IAED;;;;;;OAMG;IACH,gCAEC;IAED;;;;;;OAMG;IACH,yCAEC;IAGD,4BAMC;IAoMD;;;OAGG;IACH,YAFW,eAAe,QAoCzB;IAED;;;;;;;;;OASG;IACH,gBAFW,OAAO,+BAA+B,EAAE,YAAY,QAkC9D;IAED;;;;;;OAMG;IACH,uBAHW,sBAAsB,mCA6BhC;IAwED,gBAUC;;CACJ;8BA1lBY,OAAO,0CAA0C,EAAE,eAAe;8BAClE,OAAO,uBAAuB,EAAE,eAAe;8BAC/C,OAAO,6BAA6B,EAAE,eAAe;8BACrD,OAAO,sBAAsB,EAAE,eAAe;4BA7B/B,gCAAgC;yCACnB,2CAA2C;kCAClD,iCAAiC;uCAH5B,wCAAwC"}

package/src/shade/renderer/light/GPULightCollection.js

@@ -7,10 +7,8 @@ import { GPUSceneShadowmapContext } from "../shadow/map/GPUSceneShadowmapContext
 import { GPUTextureContext } from "../texture/GPUTextureContext.js";
 import { texture_mip_level_count } from "../../util/texture_mip_extent.js";
 import { texture_write_to_gpu } from "../texture/texture_write_to_gpu.js";
-import {
-    enquire_filter_environment_map_pipelines,
-    execute_filter_environment_map
-} from "./environment/execute_filter_environment_map.js";
+import { enquire_filter_environment_map_pipelines } from "./environment/execute_filter_environment_map.js";
+import { encode_filter_environment_map } from "./environment/graph_filter_environment_map.js";
 import { SPHERE_PROBE_MIPMAP_LEVELS } from "./environment/DEFINES.js";
 import { octahedral_skirt_matches } from "./environment/octahedral_skirt_matches.js";
 import { ENVIRONMENT_SH_TYPE, shader_project_environment_sh } from "./environment/shader_project_environment_sh.js";
@@ -398,7 +396,7 @@ export class GPULightCollection {
         // convolve
         const cmd = ShadeGPUCommandContext.create(ctx);
 
-        execute_filter_environment_map(gpu_ctx, cmd);
+        encode_filter_environment_map(gpu_ctx, cmd);
 
         // after the prefilter, whose roughest levels are what it reads
         shader_project_environment_sh.dispatch({

package/src/shade/renderer/light/environment/execute_filter_environment_map.d.ts

@@ -1,17 +1,25 @@
 /**
- * @typedef {import("../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
- */
-/**
- * Offer the pipeline {@link execute_filter_environment_map} dispatches — see {@link PipelineEnquiry}.
+ * Offer the pipelines {@link execute_filter_environment_map} dispatches — see {@link PipelineEnquiry}.
  *
  * @param {PipelineEnquiry} enquiry
  */
 export function enquire_filter_environment_map_pipelines(enquiry: PipelineEnquiry): void;
+/**
+ * The plain averages of a map's level 0 the prefilter's level 1 samples from: level 1 down as far as
+ * its samples reach, as a texture of their own, so the map keeps its levels 1.. for the filtered
+ * result. Nothing reads them after the prefilter, so a frame graph holds them transiently.
+ *
+ * @param {number} map_size side of the map's level 0
+ * @returns {TextureResourceDescriptor}
+ */
+export function environment_map_averages_descriptor(map_size: number): TextureResourceDescriptor;
 /**
  *
  * @param {GPUTextureContext} map
+ * @param {GPUTextureContext} averages described by {@link environment_map_averages_descriptor}
  * @param {ShadeGPUCommandContext} encoder
  */
-export function execute_filter_environment_map(map: GPUTextureContext, encoder: ShadeGPUCommandContext): void;
+export function execute_filter_environment_map(map: GPUTextureContext, averages: GPUTextureContext, encoder: ShadeGPUCommandContext): void;
 export type PipelineEnquiry = import("../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry;
+import { TextureResourceDescriptor } from "../../../device/graph/TextureResourceDescriptor.js";
 //# sourceMappingURL=execute_filter_environment_map.d.ts.map

package/src/shade/renderer/light/environment/execute_filter_environment_map.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"execute_filter_environment_map.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/light/environment/execute_filter_environment_map.js"],"names":[],"mappings":"AAKA;;GAEG;AAEH;;;;GAIG;AACH,kEAFW,eAAe,QAIzB;AAED;;;;GAIG;AACH,8GAkDC;8BAnEY,OAAO,6CAA6C,EAAE,eAAe"}
+{"version":3,"file":"execute_filter_environment_map.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/light/environment/execute_filter_environment_map.js"],"names":[],"mappings":"AAuBA;;;;GAIG;AACH,kEAFW,eAAe,QAMzB;AAsBD;;;;;;;GAOG;AACH,8DAHW,MAAM,GACJ,yBAAyB,CAyBrC;AAED;;;;;GAKG;AACH,2IA0GC;8BAzLY,OAAO,6CAA6C,EAAE,eAAe;0CAZxC,oDAAoD"}

package/src/shade/renderer/light/environment/execute_filter_environment_map.js

@@ -1,31 +1,103 @@
 import { assert } from "../../../../core/assert.js";
 import { TextureViewDescriptor } from "../../../descriptor/texture/TextureViewDescriptor.js";
-import { SPHERE_PROBE_MIPMAP_LEVELS } from "./DEFINES.js";
+import { TextureResourceDescriptor } from "../../../device/graph/TextureResourceDescriptor.js";
+import { cone_cosine_from_roughness } from "../../../../core/math/physics/brdf/cone_cosine_from_roughness.js";
+import { BSDF_ROUGHNESS_MINIMUM, SPHERE_PROBE_MIPMAP_LEVELS } from "./DEFINES.js";
 import { shader_convolve_reflection_map } from "./shader_convolve_reflection_map.js";
+import {
+    CONVOLVE_FROM_AVERAGES_SAMPLE_COUNT,
+    shader_convolve_reflection_map_from_averages
+} from "./shader_convolve_reflection_map_from_averages.js";
+import { shader_downsample_environment_map } from "./shader_downsample_environment_map.js";
+import { sphere_probe_lod_to_roughness } from "./sphere_probe_lod_to_roughness.js";
 
 /**
  * @typedef {import("../../../device/pipeline/PipelineEnquiry.js").PipelineEnquiry} PipelineEnquiry
  */
 
 /**
- * Offer the pipeline {@link execute_filter_environment_map} dispatches — see {@link PipelineEnquiry}.
+ * The smallest side a skirted level of the averages goes down to: two interior texels.
+ * @type {number}
+ */
+const AVERAGES_MIN_SIZE = 4;
+
+/**
+ * Offer the pipelines {@link execute_filter_environment_map} dispatches — see {@link PipelineEnquiry}.
  *
  * @param {PipelineEnquiry} enquiry
  */
 export function enquire_filter_environment_map_pipelines(enquiry) {
+    enquiry.compute.push(shader_downsample_environment_map.pipeline);
+    enquiry.compute.push(shader_convolve_reflection_map_from_averages.pipeline);
     enquiry.compute.push(shader_convolve_reflection_map.pipeline);
 }
 
+/**
+ * How many averages level 1's samples reach. A sample reads the level whose texel is the solid angle
+ * it stands for, and the coarsest it asks for is where the octahedron's texels are smallest
+ * (|d|_1 = 1): the lod `shader_convolve_reflection_map_from_averages` takes, at its largest. 3 for a
+ * 1024 map, one more for each doubling.
+ *
+ * @param {number} map_size side of the map's level 0
+ * @returns {number}
+ */
+function averages_read_by_level_1(map_size) {
+    const roughness = Math.max(sphere_probe_lod_to_roughness(1), BSDF_ROUGHNESS_MINIMUM);
+    const cone_solid_angle = 2 * Math.PI * (1 - cone_cosine_from_roughness(roughness));
+    const sample_solid_angle = cone_solid_angle / CONVOLVE_FROM_AVERAGES_SAMPLE_COUNT;
+
+    const interior = map_size - 2;
+    const smallest_texel_solid_angle = 4 / (interior * interior);
+
+    return Math.max(1, Math.ceil(0.5 * Math.log2(sample_solid_angle / smallest_texel_solid_angle)));
+}
+
+/**
+ * The plain averages of a map's level 0 the prefilter's level 1 samples from: level 1 down as far as
+ * its samples reach, as a texture of their own, so the map keeps its levels 1.. for the filtered
+ * result. Nothing reads them after the prefilter, so a frame graph holds them transiently.
+ *
+ * @param {number} map_size side of the map's level 0
+ * @returns {TextureResourceDescriptor}
+ */
+export function environment_map_averages_descriptor(map_size) {
+    assert.isNonNegativeInteger(map_size, 'map_size');
+
+    const size = map_size >> 1;
+
+    let available = 0;
+    for (let s = size; s >= AVERAGES_MIN_SIZE; s >>= 1) {
+        available++;
+    }
+
+    assert.greaterThanOrEqual(available, 1, 'environment map too small to average');
+
+    const mipLevelCount = Math.min(available, averages_read_by_level_1(map_size));
+
+    const descriptor = TextureResourceDescriptor.from({
+        resolution: [size, size],
+        format: "rgba16float",
+        usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.STORAGE_BINDING,
+    });
+
+    descriptor.mipLevelCount = mipLevelCount;
+
+    return descriptor;
+}
+
 /**
  *
  * @param {GPUTextureContext} map
+ * @param {GPUTextureContext} averages described by {@link environment_map_averages_descriptor}
  * @param {ShadeGPUCommandContext} encoder
  */
 export function execute_filter_environment_map(
     map,
+    averages,
     encoder
 ) {
     assert.defined(map);
+    assert.defined(averages);
     assert.defined(encoder);
 
     /*
@@ -45,6 +117,39 @@ export function execute_filter_environment_map(
     */
     const mips = Math.min(map.descriptor.mipLevelCount, SPHERE_PROBE_MIPMAP_LEVELS);
 
+    if (mips < 2) {
+        return;
+    }
+
+    const level_0 = map.obtainView(TextureViewDescriptor.from({
+        baseMipLevel: 0,
+        mipLevelCount: 1,
+    }));
+
+    // the averages, each from the one above it, the first from level 0
+    const average_levels = averages.descriptor.mipLevelCount;
+
+    for (let i = 0; i < average_levels; i++) {
+        const target_size = averages.size[0] >> i;
+        const group_count = Math.max(1, Math.ceil(target_size / 16));
+
+        shader_downsample_environment_map.dispatch({
+            encoder,
+            group_count_x: group_count,
+            group_count_y: group_count,
+            bindings: {
+                input: i === 0 ? level_0 : averages.obtainView(TextureViewDescriptor.from({
+                    baseMipLevel: i - 1,
+                    mipLevelCount: 1,
+                })),
+                output: averages.obtainView(TextureViewDescriptor.from({
+                    baseMipLevel: i,
+                    mipLevelCount: 1
+                }))
+            }
+        });
+    }
+
     for (let i = 1; i < mips; i++) {
         const target_width = map.size[0] >> i;
         const target_height = map.size[1] >> i;
@@ -54,6 +159,30 @@ export function execute_filter_environment_map(
         const dispatch_x = Math.max(1, Math.ceil(target_width / 16));
         const dispatch_y = Math.max(1, Math.ceil(target_height / 16));
 
+        const output = map.obtainView(TextureViewDescriptor.from({
+            baseMipLevel: i,
+            mipLevelCount: 1
+        }));
+
+        if (i === 1) {
+            // from level 0 and its averages: level 0 is too fine for the taps that cover level 1's cone
+            shader_convolve_reflection_map_from_averages.dispatch({
+                encoder,
+                group_count_x: dispatch_x,
+                group_count_y: dispatch_y,
+                bindings: {
+                    level_0,
+                    averages: averages.obtainView(TextureViewDescriptor.from({
+                        baseMipLevel: 0,
+                        mipLevelCount: average_levels,
+                    })),
+                    output
+                }
+            });
+
+            continue;
+        }
+
         shader_convolve_reflection_map.dispatch({
             encoder,
             group_count_x: dispatch_x,
@@ -64,11 +193,8 @@ export function execute_filter_environment_map(
                     baseMipLevel: i - 1,
                     mipLevelCount: 1,
                 })),
-                output: map.obtainView(TextureViewDescriptor.from({
-                    baseMipLevel: i,
-                    mipLevelCount: 1
-                }))
+                output
             }
         });
     }
-}
+}

package/src/shade/renderer/light/environment/graph_filter_environment_map.d.ts

@@ -9,4 +9,13 @@ export function graph_filter_environment_map({ graph, map, }: {
     graph: FrameGraph;
     map: number;
 }): number;
+/**
+ * Prefilter a map outside a frame graph of the caller's: one of its own, so the averages are still
+ * transient.
+ *
+ * @param {GPUTextureContext} map
+ * @param {ShadeGPUCommandContext} encoder
+ */
+export function encode_filter_environment_map(map: GPUTextureContext, encoder: ShadeGPUCommandContext): void;
+import { FrameGraph } from "../../../../engine/graphics/render/frame_graph/FrameGraph.js";
 //# sourceMappingURL=graph_filter_environment_map.d.ts.map

package/src/shade/renderer/light/environment/graph_filter_environment_map.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph_filter_environment_map.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/light/environment/graph_filter_environment_map.js"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH;IAJ+B,KAAK;IACT,GAAG,EAAnB,MAAM;IACJ,MAAM,CAgClB"}
+{"version":3,"file":"graph_filter_environment_map.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/light/environment/graph_filter_environment_map.js"],"names":[],"mappings":"AAOA;;;;;;GAMG;AACH;IAJ+B,KAAK,EAAzB,UAAU;IACM,GAAG,EAAnB,MAAM;IACJ,MAAM,CAmClB;AAED;;;;;;GAMG;AACH,6GAYC;2BApE0B,8DAA8D"}

package/src/shade/renderer/light/environment/graph_filter_environment_map.js

@@ -1,4 +1,9 @@
-import { execute_filter_environment_map } from "./execute_filter_environment_map.js";
+import { FrameGraph } from "../../../../engine/graphics/render/frame_graph/FrameGraph.js";
+import { TextureResourceDescriptor } from "../../../device/graph/TextureResourceDescriptor.js";
+import {
+    environment_map_averages_descriptor,
+    execute_filter_environment_map
+} from "./execute_filter_environment_map.js";
 
 /**
  * @see https://github.com/mrdoob/three.js/blob/efb7510951afff90c90fd2c969675285e374b0be/src/extras/PMREMGenerator.js#L32
@@ -27,14 +32,38 @@ export function graph_filter_environment_map({
          */
         const map = resources.get(data.map);
 
-        execute_filter_environment_map(map, context.encoder);
+        execute_filter_environment_map(map, resources.get(data.averages), context.encoder);
 
     }
 
     const builder = graph.add("filter env map", data, execute);
 
-
     data.map = builder.read(map);
+    data.averages = builder.create(
+        "env map averages",
+        environment_map_averages_descriptor(graph.getDescriptor(map).resolution[0])
+    );
 
     return builder.write(map);
-}
+}
+
+/**
+ * Prefilter a map outside a frame graph of the caller's: one of its own, so the averages are still
+ * transient.
+ *
+ * @param {GPUTextureContext} map
+ * @param {ShadeGPUCommandContext} encoder
+ */
+export function encode_filter_environment_map(map, encoder) {
+    const graph = new FrameGraph("environment map prefilter");
+
+    const imported = graph.import_resource(
+        "environment map",
+        TextureResourceDescriptor.fromTexture(map.gpu_texture),
+        map
+    );
+
+    graph_filter_environment_map({ graph, map: imported });
+
+    encoder.encodeGraph(graph);
+}

package/src/shade/renderer/light/environment/shader_convolve_reflection_map_from_averages.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Samples per texel. Each reads the average whose texel matches the solid angle it stands for, so
+ * fewer samples read coarser averages and more read finer ones, back toward point taps that catch or
+ * miss a bright texel. Measured on a single bright texel of a 1024 map at 48 places, level 1 over
+ * level 0 in solid-angle energy: 32 → 0.995 ± 0.014, 64 → 0.998 ± 0.008 (at most 1.005),
+ * 196 → 1.001 ± 0.019 — at 196 the lod is 0.5 .. 1.7, and every read below 1 blends in level 0's
+ * point taps. UE filters with 32 below roughness 0.1 and 64 above.
+ * @type {number}
+ */
+export const CONVOLVE_FROM_AVERAGES_SAMPLE_COUNT: number;
+export const shader_convolve_reflection_map_from_averages: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_convolve_reflection_map_from_averages.d.ts.map

package/src/shade/renderer/light/environment/shader_convolve_reflection_map_from_averages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_convolve_reflection_map_from_averages.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/light/environment/shader_convolve_reflection_map_from_averages.js"],"names":[],"mappings":"AAqCA;;;;;;;;GAQG;AACH,kDAFU,MAAM,CAEsC;AAmJtD,yEAII;8BAlL0B,+BAA+B"}

package/src/shade/renderer/light/environment/shader_convolve_reflection_map_from_averages.js

@@ -0,0 +1,198 @@
+import { chunk_cone_cosine_from_roughness } from "../../shader/chunk/brdf/chunk_cone_cosine_from_roughness.js";
+import {
+    chunk_build_orthonormal_matrix_n
+} from "../../shader/chunk/geometry/normal/chunk_build_orthonormal_matrix_n.js";
+import {
+    chunk_uv_octahedral_unit_decode
+} from "../../shader/chunk/geometry/octahedron/chunk_uv_octahedral_unit_decode.js";
+import {
+    chunk_uv_octahedral_unit_encode
+} from "../../shader/chunk/geometry/octahedron/chunk_uv_octahedral_unit_encode.js";
+import { chunk_uniform_sample_cone } from "../../shader/chunk/geometry/ray/chunk_uniform_sample_cone.js";
+import { chunk_pow2 } from "../../shader/chunk/math/chunk_pow2.js";
+import { chunk_safe_rcp } from "../../shader/chunk/math/chunk_safe_rcp.js";
+import { chunk_hammersley_2d } from "../../shader/chunk/noise/chunk_hammersley_2d.js";
+import {
+    chunk_texture_octahedral_skirt_texel_uv
+} from "../../shader/chunk/texture/octahedral/chunk_texture_octahedral_skirt_texel_uv.js";
+import { chunk_texture_octahedral_skirt_uv } from "../../shader/chunk/texture/octahedral/chunk_texture_octahedral_skirt_uv.js";
+import { CodeChunk } from "../../shader/compiler/CodeChunk.js";
+import { ComputeShader } from "../../shader/ComputeShader.js";
+import { ShaderResourceSetDescriptor } from "../../shader/resource/ShaderResourceSetDescriptor.js";
+import { ShaderDescriptor } from "../../shader/ShaderDescriptor.js";
+import { chunk_reflection_sample_weight } from "./chunk_reflection_sample_weight.js";
+import { chunk_sphere_probe_lod_to_roughness } from "./chunk_sphere_probe_lod_to_roughness.js";
+import { BSDF_ROUGHNESS_MINIMUM } from "./DEFINES.js";
+import { ENVIRONMENT_MAP_SAMPLER_RESOURCE } from "./ENVIRONMENT_MAP_SAMPLER_RESOURCE.js";
+
+const resources = new ShaderResourceSetDescriptor();
+
+resources.createGroup()
+    // the map's level 0, and its plain averages from level 1 down (see shader_downsample_environment_map)
+    .addTexture("level_0", "float")
+    .addTexture("averages", "float")
+    .addStorageTexture("output", "rgba16float")
+    .add(ENVIRONMENT_MAP_SAMPLER_RESOURCE)
+;
+
+/**
+ * Samples per texel. Each reads the average whose texel matches the solid angle it stands for, so
+ * fewer samples read coarser averages and more read finer ones, back toward point taps that catch or
+ * miss a bright texel. Measured on a single bright texel of a 1024 map at 48 places, level 1 over
+ * level 0 in solid-angle energy: 32 → 0.995 ± 0.014, 64 → 0.998 ± 0.008 (at most 1.005),
+ * 196 → 1.001 ± 0.019 — at 196 the lod is 0.5 .. 1.7, and every read below 1 blends in level 0's
+ * point taps. UE filters with 32 below roughness 0.1 and 64 above.
+ * @type {number}
+ */
+export const CONVOLVE_FROM_AVERAGES_SAMPLE_COUNT = 64;
+
+/**
+ * How much a read of the averages widens the lobe, as mean squared angle per steradian a sample
+ * stands for. The lobe exp(2 (N·H - 1) / r^4) is a Gaussian of mean squared angle 4 r^4 (N·H =
+ * cos(θ/2), so N·H - 1 ≈ -θ²/8), and convolving adds variances, so the lobe is narrowed to
+ * r^4 - k Ω_s / 4 and lands at the width it is asked for.
+ *
+ * A box over the texel plus the bilinear tent across its neighbours predicts 1/2; 1 is measured. On
+ * a 1024 map's sun against level 1 from 8192 point taps (1.315° rms): k = 0 → 1.436°, 1/2 → 1.380°,
+ * 1 → 1.317°; the sun's tail error 110% → 49%. The two reads a lod between levels blends, and an
+ * average's footprint 2 + 2/n texels of the one above rather than 2, are the likely difference.
+ * Matching the width leaves the shape: the core is flatter than a Gaussian, and the sky's rms error
+ * against the reference goes 0.166 → 0.222.
+ * @type {number}
+ */
+const AVERAGES_BLUR_PER_SOLID_ANGLE = 1;
+
+/**
+ * Level 1 of the prefilter, by filtered importance sampling: each sample reads the plain average of
+ * level 0 whose texel is the solid angle the sample stands for, so a texel brighter than its
+ * neighbours is averaged into the coarser texel the sample reads instead of being hit or missed by
+ * the sample pattern. Point taps into level 0 — 196 of them over a cone of 639 level-0 texels — put
+ * one bright texel's share of level 1 anywhere from 0.79 to 1.21 of its energy, and an HDR sun
+ * came out 0.66% brighter than it went in.
+ *
+ * Samples are uniform in the cone, so each stands for the same solid angle and reads the same
+ * average: the averages blur the lobe by one fixed amount, which the lobe gives back by narrowing
+ * (see AVERAGES_BLUR_PER_SOLID_ANGLE). UE's importance sampling read fine averages in the lobe's core
+ * and coarse ones in its tail, and the sun came out in blocks.
+ *
+ * Level 1 only. The levels after it read the level above, already smooth at their sample spacing
+ * (see shader_convolve_reflection_map). Read from level 0 instead, their samples land on averages
+ * 8 to 16 texels a side, too coarse an octahedral grid to keep a bright texel's energy: ±11% at
+ * level 4, and a sky 11% brighter.
+ *
+ * @see https://developer.nvidia.com/gpugems/gpugems3/part-iii-rendering/chapter-20-gpu-based-importance-sampling
+ * @see https://github.com/EpicGames/UnrealEngine/blob/5.4/Engine/Shaders/Private/ReflectionEnvironmentShaders.usf FilterPS
+ * @see https://projects.blender.org/blender/blender/src/commit/866ef5b468589587395b1ee7480ea75b4c0fbc26/source/blender/draw/engines/eevee_next/shaders/eevee_lightprobe_sphere_convolve_comp.glsl for the lobe
+ * @type {CodeChunk}
+ */
+const body = CodeChunk.from(
+    //language=WGSL
+    `
+/// level 0 is the map's own, the levels below it are the averages
+fn sample_source_level(direction: vec3<f32>, level: u32) -> vec4<f32> {
+    let uv = uv_octahedral_unit_encode(direction);
+
+    if (level == 0u) {
+        let size = f32(textureDimensions(level_0).x);
+
+        return textureSampleLevel(level_0, sEnvironment, texture_octahedral_skirt_uv(uv, size), 0.0);
+    }
+
+    let average_level = level - 1u;
+    let size = f32(textureDimensions(averages, average_level).x);
+
+    return textureSampleLevel(averages, sEnvironment, texture_octahedral_skirt_uv(uv, size), f32(average_level));
+}
+
+@compute @workgroup_size(16,16,1)
+fn main(
+    @builtin(global_invocation_id) global_invocation_id : vec3<u32>,
+){
+    let output_size = textureDimensions(output);
+
+    let output_texel_i = global_invocation_id.xy;
+
+    if(any(output_texel_i >= output_size)){
+        return;
+    }
+
+    /* From mip to linear roughness (same as UI). */
+    let roughness = max(sphere_probe_lod_to_roughness(1.0), ${BSDF_ROUGHNESS_MINIMUM});
+    let cone_cos = cone_cosine_from_roughness(roughness);
+
+    // the skirt too: a skirt texel takes its interior twin's uv, so it is that texel, computed again
+    let out_uv = texture_octahedral_skirt_texel_uv(output_texel_i, output_size.x);
+    let out_direction = uv_octahedral_unit_decode( out_uv );
+
+    let basis = build_orthonormal_matrix_n(out_direction);
+
+    var weight_accum = 0.0;
+    var radiance_accum = vec4(0.0);
+
+    const sample_count = ${CONVOLVE_FROM_AVERAGES_SAMPLE_COUNT};
+
+    // uniform in the cone, so every sample stands for the same solid angle
+    let sample_solid_angle = 2.0 * PI * (1.0 - cone_cos) / f32(sample_count);
+
+    // narrowed by the blur the averages add, so the lobe comes out at the roughness asked for
+    let lobe_roughness = sqrt(sqrt(max(
+        pow2(pow2(roughness)) - ${AVERAGES_BLUR_PER_SOLID_ANGLE.toFixed(6)} * sample_solid_angle / 4.0,
+        pow2(pow2(${BSDF_ROUGHNESS_MINIMUM}))
+    )));
+
+    // level 0's octahedral square, n texels a side, spans 2 in octahedron coordinates; a texel there
+    // covers (2/n)^2 of it, and the octahedron's solid angle per unit area is |d|_1^3 along unit d
+    let level_0_interior = f32(textureDimensions(level_0).x) - 2.0;
+    let level_0_texel_area = 4.0 / (level_0_interior * level_0_interior);
+
+    let last_level = f32(textureNumLevels(averages));
+
+    for (var i = 0u; i < sample_count; i++) {
+        let rand = hammersley_2d(i, sample_count);
+
+        let in_direction = normalize(basis * uniform_sample_cone(rand, cone_cos));
+
+        let l1 = dot(abs(in_direction), vec3(1.0));
+        let texel_solid_angle = level_0_texel_area * l1 * l1 * l1;
+
+        let lod = clamp(0.5 * log2(sample_solid_angle / texel_solid_angle), 0.0, last_level);
+        let lod_floor = floor(lod);
+        let level = u32(lod_floor);
+
+        let radiance = mix(
+            sample_source_level(in_direction, level),
+            sample_source_level(in_direction, min(level + 1u, u32(last_level))),
+            lod - lod_floor
+        );
+
+        let weight = reflection_sample_weight(out_direction, in_direction, lobe_roughness);
+
+        radiance_accum += radiance * weight;
+        weight_accum += weight;
+    }
+
+    let out_radiance = radiance_accum * safe_rcp(weight_accum);
+
+    textureStore(output, output_texel_i, out_radiance);
+}
+    `, [
+        chunk_sphere_probe_lod_to_roughness,
+        chunk_hammersley_2d,
+        chunk_build_orthonormal_matrix_n,
+        chunk_safe_rcp,
+        chunk_pow2,
+        chunk_uniform_sample_cone,
+        chunk_texture_octahedral_skirt_texel_uv,
+        chunk_texture_octahedral_skirt_uv,
+        chunk_uv_octahedral_unit_decode,
+        chunk_uv_octahedral_unit_encode,
+        chunk_reflection_sample_weight,
+        chunk_cone_cosine_from_roughness,
+    ]
+);
+
+export const shader_convolve_reflection_map_from_averages = new ComputeShader(ShaderDescriptor.from({
+    label: 'Convolve reflection map from averages',
+    body,
+    resources
+}));

package/src/shade/renderer/light/environment/shader_downsample_environment_map.d.ts

@@ -0,0 +1,3 @@
+export const shader_downsample_environment_map: ComputeShader;
+import { ComputeShader } from "../../shader/ComputeShader.js";
+//# sourceMappingURL=shader_downsample_environment_map.d.ts.map

package/src/shade/renderer/light/environment/shader_downsample_environment_map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shader_downsample_environment_map.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/light/environment/shader_downsample_environment_map.js"],"names":[],"mappings":"AAoGA,8DAII;8BAjG0B,+BAA+B"}