@aura3d/rendering 4.3.7 → 4.5.0

package/dist/webgl2/LegacyPost.js

@@ -5,6 +5,7 @@ import { temporalAccumulationWeight } from "../TemporalMath.js";
 import { WebGL2RenderTarget } from "../WebGL2Device.js";
 import { normalizeBloomQualityPreset, resolveBloomPyramidBlurRadii, resolveBloomPyramidPlan, resolveBloomPyramidResponseGain, resolveBloomPyramidV2Response } from "../postprocess/NativeBloomPyramid.js";
 import { BLOOM_BRIGHT_LUT_HEIGHT, BLOOM_BRIGHT_LUT_WIDTH, BLOOM_COMPOSITE_LUT_SIZE, OUTLINE_BLEND_LUT_WIDTH, OUTLINE_LIMB_RADIX, createBloomBrightThresholdLut, createBloomCompositeLut, createOutlineBlendLut, createOutlineGradientBound } from "../postprocess/NativeLdrEffectLuts.js";
+import { BLOOM_FUSED_BLUR_TAP_BUDGET, bloomLevelBlursIn2d } from "./BloomFusion.js";
 // PRD-03 Phase 1 — the r185 FXAA finalize (post/shaders/fxaa.glsl.ts). The
 // split is opt-in via `fxaa: { variant: "r185" }`; the legacy in-shader
 // `u_hasFxaa` taps stay the default path.
@@ -14,12 +15,24 @@ import { vignetteColorRgb } from "../post/vignetteColor.js";
 import { outputPassForDevice } from "../output/OutputPass.js";
 import { TONE_MAP_OPERATOR_FUNCTIONS } from "../output/ToneMappingOperators.glsl.js";
 import { ldrFragmentSource, ldrVariantKey } from "./LdrPostprocessShader.js";
+/** Pass fusion (auto/cinematic): the fused mip sum samples at most this many mips in one pass. */
+export const BLOOM_FUSED_MAX_MIPS = 5;
+export { BLOOM_FUSED_BLUR_TAP_BUDGET };
+/** Texture units the fullscreen presentation snapshot saves and restores: 0..4 (the fused bloom mip sum samples five). */
+export const PRESENTATION_TEXTURE_UNITS = BLOOM_FUSED_MAX_MIPS;
 export class WebGL2LegacyPostPipeline {
     host;
     constructor(host) {
         this.host = host;
     }
     bloomAccumulateProgram = null;
+    /** Look-neutral pass fusion (auto/cinematic only): single-pass 2-D Gaussian for small mips, one-pass weighted mip sum, upsample folded into the composite. */
+    bloomBlur2dProgram = null;
+    bloomFusedAccumulateProgram = null;
+    bloomFusedCompositeProgram = null;
+    bloomPrefilterDownsampleProgram = null;
+    /** True when the last `executeNativeBloomPyramidPasses` returned the level-0 accumulator (not a full-resolution copy). */
+    lastPyramidFused = false;
     bloomBlurProgram = null;
     bloomBrightExtractProgram = null;
     bloomBrightLutTexture = null;
@@ -211,17 +224,19 @@ export class WebGL2LegacyPostPipeline {
                     // source through the proven single-scale composite program.
                     this.host.gl.bindFramebuffer(this.host.gl.FRAMEBUFFER, bloomResources.framebuffers[1]);
                     this.host.gl.viewport(0, 0, source.width, source.height);
-                    const pyramidComposite = this.ensureBloomCompositeProgram();
+                    const pyramidComposite = this.lastPyramidFused ? this.ensureBloomFusedCompositeProgram() : this.ensureBloomCompositeProgram();
                     this.host.gl.useProgram(pyramidComposite);
                     this.host.gl.bindVertexArray(vertexArray);
                     this.bindFullscreenTexture(0, ldrSourceHandle);
                     this.bindFullscreenTexture(1, pyramidResult);
-                    if (this.bloomCompositeLutTexture)
+                    if (this.bloomCompositeLutTexture && !this.lastPyramidFused)
                         this.bindFullscreenTexture(2, this.bloomCompositeLutTexture);
                     this.host.gl.uniform1i(this.host.gl.getUniformLocation(pyramidComposite, "u_source"), 0);
                     this.host.gl.uniform1i(this.host.gl.getUniformLocation(pyramidComposite, "u_blurred"), 1);
-                    this.host.gl.uniform1i(this.host.gl.getUniformLocation(pyramidComposite, "u_compositeLut"), 2);
-                    this.host.gl.uniform1i(this.host.gl.getUniformLocation(pyramidComposite, "u_hdr"), sourceIsHdr ? 1 : 0);
+                    if (!this.lastPyramidFused) {
+                        this.host.gl.uniform1i(this.host.gl.getUniformLocation(pyramidComposite, "u_compositeLut"), 2);
+                        this.host.gl.uniform1i(this.host.gl.getUniformLocation(pyramidComposite, "u_hdr"), sourceIsHdr ? 1 : 0);
+                    }
                     this.host.gl.uniform1f(this.host.gl.getUniformLocation(pyramidComposite, "u_intensity"), bloomOptions.intensity * nativeBloomResponseGain(plan, bloomOptions));
                     this.host.gl.drawArrays(this.host.gl.TRIANGLES, 0, 3);
                     ldrSourceHandle = bloomResources.textures[1];
@@ -343,17 +358,19 @@ export class WebGL2LegacyPostPipeline {
                 }, bloomOptions, vertexArray, true);
                 this.host.gl.bindFramebuffer(this.host.gl.FRAMEBUFFER, destination.framebuffer);
                 this.host.gl.viewport(0, 0, source.width, source.height);
-                const composite = this.ensureBloomCompositeProgram();
+                const composite = this.lastPyramidFused ? this.ensureBloomFusedCompositeProgram() : this.ensureBloomCompositeProgram();
                 this.host.gl.useProgram(composite);
                 this.host.gl.bindVertexArray(vertexArray);
                 this.bindFullscreenTexture(0, source.colorHandle);
                 this.bindFullscreenTexture(1, pyramidResult);
-                if (this.bloomCompositeLutTexture)
+                if (this.bloomCompositeLutTexture && !this.lastPyramidFused)
                     this.bindFullscreenTexture(2, this.bloomCompositeLutTexture);
                 this.host.gl.uniform1i(this.host.gl.getUniformLocation(composite, "u_source"), 0);
                 this.host.gl.uniform1i(this.host.gl.getUniformLocation(composite, "u_blurred"), 1);
-                this.host.gl.uniform1i(this.host.gl.getUniformLocation(composite, "u_compositeLut"), 2);
-                this.host.gl.uniform1i(this.host.gl.getUniformLocation(composite, "u_hdr"), 1);
+                if (!this.lastPyramidFused) {
+                    this.host.gl.uniform1i(this.host.gl.getUniformLocation(composite, "u_compositeLut"), 2);
+                    this.host.gl.uniform1i(this.host.gl.getUniformLocation(composite, "u_hdr"), 1);
+                }
                 this.host.gl.uniform1f(this.host.gl.getUniformLocation(composite, "u_intensity"), bloomOptions.intensity * nativeBloomResponseGain(plan, bloomOptions));
                 this.host.gl.drawArrays(this.host.gl.TRIANGLES, 0, 3);
                 this.recordBloomDiagnostics(bloomOptions, source.width, source.height, true, plan.mipCount);
@@ -669,8 +686,16 @@ export class WebGL2LegacyPostPipeline {
         const mipTexture = (level, slot) => resources.textures[level * 2 + slot];
         const mipFramebuffer = (level, slot) => resources.framebuffers[level * 2 + slot];
         const mipSize = (level) => plan.mips[level];
-        // Every level settles in slot 0 after the vertical blur.
-        const blurredSlot = (_level) => 0;
+        // Pass fusion (hdr-msaa path under quality auto/cinematic; `production` never sets the device flag): small mips blur in one
+        // 2-D pass, the mip sum is one pass, and the final full-resolution upsample is folded into the composite.
+        const fused = hdr && this.host.device.bloomFusedPasses === true && mipCount <= BLOOM_FUSED_MAX_MIPS;
+        const fusion = this.host.device.bloomFusion;
+        const fuseAccumulate = fused && fusion.accumulate;
+        this.lastPyramidFused = fuseAccumulate;
+        // Every level settles in slot 0 after the two-pass vertical blur; a single-pass 2-D blur settles in slot 1.
+        const settledSlot = [];
+        const blurredSlot = (level) => settledSlot[level] ?? 0;
+        const blur2dProgram = fused && fusion.blur2dFromLevel < mipCount ? this.ensureBloomBlur2dProgram() : null;
         const drawDownsample = (fromTexture, fromWidth, fromHeight, toFramebuffer, toWidth, toHeight) => {
             this.host.gl.bindFramebuffer(this.host.gl.FRAMEBUFFER, toFramebuffer);
             this.host.gl.viewport(0, 0, toWidth, toHeight);
@@ -716,35 +741,95 @@ export class WebGL2LegacyPostPipeline {
             this.host.gl.uniform1i(this.host.gl.getUniformLocation(blurProgram, "u_horizontal"), 0);
             this.host.gl.drawArrays(this.host.gl.TRIANGLES, 0, 3);
         };
+        // Blur one mip that was just downsampled into slot 0. Two passes (H into slot 1, V back into slot 0) normally; a single
+        // 2-D pass (slot 0 into slot 1) when fusion is on and the tap count stays under the budget.
+        const blurLevel = (level, size, radius) => {
+            if (blur2dProgram && bloomLevelBlursIn2d(fusion, level, size, radius)) {
+                this.host.gl.bindFramebuffer(this.host.gl.FRAMEBUFFER, mipFramebuffer(level, 1));
+                this.host.gl.viewport(0, 0, size.width, size.height);
+                this.host.gl.useProgram(blur2dProgram);
+                this.host.gl.bindVertexArray(vertexArray);
+                this.bindFullscreenTexture(0, mipTexture(level, 0));
+                this.host.gl.uniform1i(this.host.gl.getUniformLocation(blur2dProgram, "u_source"), 0);
+                this.host.gl.uniform2i(this.host.gl.getUniformLocation(blur2dProgram, "u_size"), size.width, size.height);
+                this.host.gl.uniform1i(this.host.gl.getUniformLocation(blur2dProgram, "u_radius"), radius);
+                this.host.gl.drawArrays(this.host.gl.TRIANGLES, 0, 3);
+                settledSlot[level] = 1;
+                return;
+            }
+            drawSeparableBlur(mipTexture(level, 0), mipTexture(level, 1), mipFramebuffer(level, 1), mipFramebuffer(level, 0), size, radius);
+            settledSlot[level] = 0;
+        };
         // Extract highlights at the source resolution before the first downsample.
         // Downsampling the complete scene first averaged narrow emissive sources
         // below the authored threshold, so balanced/cinematic bloom could execute
         // all native passes yet remain pixel-identical to disabled output.
-        this.host.gl.bindFramebuffer(this.host.gl.FRAMEBUFFER, fullResStaging.framebufferA);
-        this.host.gl.viewport(0, 0, sourceWidth, sourceHeight);
-        this.host.gl.useProgram(brightProgram);
-        this.host.gl.bindVertexArray(vertexArray);
-        this.bindFullscreenTexture(0, sourceTexture);
-        if (brightLut)
-            this.bindFullscreenTexture(1, brightLut);
-        this.host.gl.uniform1i(this.host.gl.getUniformLocation(brightProgram, "u_source"), 0);
-        this.host.gl.uniform1i(this.host.gl.getUniformLocation(brightProgram, "u_brightLut"), 1);
-        this.host.gl.uniform1i(this.host.gl.getUniformLocation(brightProgram, "u_hdr"), hdr ? 1 : 0);
-        this.host.gl.uniform1f(this.host.gl.getUniformLocation(brightProgram, "u_threshold"), options.threshold);
-        this.host.gl.uniform1f(this.host.gl.getUniformLocation(brightProgram, "u_softKnee"), options.softKnee);
-        this.host.gl.uniform1i(this.host.gl.getUniformLocation(brightProgram, "u_excess"), options.excess === true ? 1 : 0);
-        this.host.gl.drawArrays(this.host.gl.TRIANGLES, 0, 3);
         // Level 0 downsamples the extracted highlight field, then blurs H into
         // slot 1 and V back into slot 0. The result therefore settles in slot 0.
         const level0 = mipSize(0);
-        drawDownsample(fullResStaging.textureA, sourceWidth, sourceHeight, mipFramebuffer(0, 0), level0.width, level0.height);
-        drawSeparableBlur(mipTexture(0, 0), mipTexture(0, 1), mipFramebuffer(0, 1), mipFramebuffer(0, 0), level0, blurRadii[0]);
+        // Extract + level-0 downsample in one pass when the source is exactly 2:1: each destination texel averages the four
+        // source texels the unfused box downsample reads (its taps land on texel centres), extracting each first, so the
+        // result matches the two-pass chain without the full-resolution extract target or its pass.
+        const extractFolded = fused && fusion.extract && level0.width * 2 === sourceWidth && level0.height * 2 === sourceHeight;
+        if (extractFolded) {
+            const prefilter = this.ensureBloomPrefilterDownsampleProgram();
+            this.host.gl.bindFramebuffer(this.host.gl.FRAMEBUFFER, mipFramebuffer(0, 0));
+            this.host.gl.viewport(0, 0, level0.width, level0.height);
+            this.host.gl.useProgram(prefilter);
+            this.host.gl.bindVertexArray(vertexArray);
+            this.bindFullscreenTexture(0, sourceTexture);
+            this.host.gl.uniform1i(this.host.gl.getUniformLocation(prefilter, "u_source"), 0);
+            this.host.gl.uniform1f(this.host.gl.getUniformLocation(prefilter, "u_threshold"), options.threshold);
+            this.host.gl.uniform1f(this.host.gl.getUniformLocation(prefilter, "u_softKnee"), options.softKnee);
+            this.host.gl.uniform1i(this.host.gl.getUniformLocation(prefilter, "u_excess"), options.excess === true ? 1 : 0);
+            this.host.gl.drawArrays(this.host.gl.TRIANGLES, 0, 3);
+        }
+        else {
+            this.host.gl.bindFramebuffer(this.host.gl.FRAMEBUFFER, fullResStaging.framebufferA);
+            this.host.gl.viewport(0, 0, sourceWidth, sourceHeight);
+            this.host.gl.useProgram(brightProgram);
+            this.host.gl.bindVertexArray(vertexArray);
+            this.bindFullscreenTexture(0, sourceTexture);
+            if (brightLut)
+                this.bindFullscreenTexture(1, brightLut);
+            this.host.gl.uniform1i(this.host.gl.getUniformLocation(brightProgram, "u_source"), 0);
+            this.host.gl.uniform1i(this.host.gl.getUniformLocation(brightProgram, "u_brightLut"), 1);
+            this.host.gl.uniform1i(this.host.gl.getUniformLocation(brightProgram, "u_hdr"), hdr ? 1 : 0);
+            this.host.gl.uniform1f(this.host.gl.getUniformLocation(brightProgram, "u_threshold"), options.threshold);
+            this.host.gl.uniform1f(this.host.gl.getUniformLocation(brightProgram, "u_softKnee"), options.softKnee);
+            this.host.gl.uniform1i(this.host.gl.getUniformLocation(brightProgram, "u_excess"), options.excess === true ? 1 : 0);
+            this.host.gl.drawArrays(this.host.gl.TRIANGLES, 0, 3);
+            drawDownsample(fullResStaging.textureA, sourceWidth, sourceHeight, mipFramebuffer(0, 0), level0.width, level0.height);
+        }
+        blurLevel(0, level0, blurRadii[0]);
         for (let level = 1; level < mipCount; level += 1) {
             const size = mipSize(level);
             const previous = mipSize(level - 1);
             drawDownsample(mipTexture(level - 1, blurredSlot(level - 1)), previous.width, previous.height, mipFramebuffer(level, 0), size.width, size.height);
             // H into slot 1, V back into slot 0: blurred result settles in slot 0.
-            drawSeparableBlur(mipTexture(level, 0), mipTexture(level, 1), mipFramebuffer(level, 1), mipFramebuffer(level, 0), size, blurRadii[level]);
+            blurLevel(level, size, blurRadii[level]);
+        }
+        if (fuseAccumulate) {
+            // Weighted mip sum in one pass (smallest to largest, as the sequential passes accumulate), left at level-0 size.
+            const fusedWeights = v2Response ? v2Response.weights : plan.weights;
+            const fusedProgram = this.ensureBloomFusedAccumulateProgram();
+            this.host.gl.bindFramebuffer(this.host.gl.FRAMEBUFFER, resources.accumulatorFramebufferA);
+            this.host.gl.viewport(0, 0, level0.width, level0.height);
+            this.host.gl.useProgram(fusedProgram);
+            this.host.gl.bindVertexArray(vertexArray);
+            const weightValues = new Float32Array(5);
+            for (let level = 0; level < 5; level += 1) {
+                // Unused samplers still need a valid texture; bind mip 0 so no unit is left pointing at the target.
+                const bound = level < mipCount ? level : 0;
+                this.bindFullscreenTexture(level, mipTexture(bound, blurredSlot(bound)));
+                this.host.gl.uniform1i(this.host.gl.getUniformLocation(fusedProgram, `u_mip${level}`), level);
+                weightValues[level] = level < mipCount ? fusedWeights[level] : 0;
+            }
+            this.host.gl.uniform1fv(this.host.gl.getUniformLocation(fusedProgram, "u_weights"), weightValues);
+            this.host.gl.uniform1i(this.host.gl.getUniformLocation(fusedProgram, "u_count"), mipCount);
+            this.host.gl.uniform2f(this.host.gl.getUniformLocation(fusedProgram, "u_targetSize"), level0.width, level0.height);
+            this.host.gl.drawArrays(this.host.gl.TRIANGLES, 0, 3);
+            return resources.accumulatorTextureA;
         }
         // Accumulate smallest-to-largest, ping-ponging between the two
         // accumulators (a pass must never sample its own bound target).
@@ -1187,6 +1272,10 @@ export class WebGL2LegacyPostPipeline {
         const textureUnit0 = this.host.lifecycle.captureTextureUnit0();
         const textureUnit1 = this.host.lifecycle.captureTextureUnitBinding(1);
         const textureUnit2 = this.host.lifecycle.captureTextureUnitBinding(2);
+        const extraTextureUnits = [];
+        for (let unit = 3; unit < PRESENTATION_TEXTURE_UNITS; unit += 1) {
+            extraTextureUnits.push({ unit, binding: this.host.lifecycle.captureTextureUnitBinding(unit) });
+        }
         this.host.gl.activeTexture(textureUnit0.activeTexture);
         const snapshot = {
             framebuffer: this.host.gl.getParameter(this.host.gl.FRAMEBUFFER_BINDING),
@@ -1194,6 +1283,7 @@ export class WebGL2LegacyPostPipeline {
             textureUnit0,
             textureUnit1,
             textureUnit2,
+            extraTextureUnits,
             vertexArray: this.host.gl.getParameter(this.host.gl.VERTEX_ARRAY_BINDING),
             viewport: this.host.gl.getParameter(this.host.gl.VIEWPORT),
             colorMask: this.host.gl.getParameter(this.host.gl.COLOR_WRITEMASK),
@@ -1218,6 +1308,10 @@ export class WebGL2LegacyPostPipeline {
     }
     restoreFullscreenPresentationState(snapshot, fallbackWidth, fallbackHeight) {
         this.host.gl.bindVertexArray(snapshot.vertexArray);
+        for (let index = snapshot.extraTextureUnits.length - 1; index >= 0; index -= 1) {
+            const extra = snapshot.extraTextureUnits[index];
+            this.host.lifecycle.restoreTextureUnitBinding(extra.unit, extra.binding);
+        }
         this.host.lifecycle.restoreTextureUnitBinding(2, snapshot.textureUnit2);
         this.host.lifecycle.restoreTextureUnitBinding(1, snapshot.textureUnit1);
         this.host.lifecycle.restoreTextureUnit0(snapshot.textureUnit0);
@@ -1417,6 +1511,144 @@ void main() {
 `, "webgl2-bloom-downsample");
         return this.bloomDownsampleProgram;
     }
+    /**
+     * Single-pass 2-D Gaussian: the product of the two normalised 1-D kernels the separable blur applies, with the same
+     * per-axis edge clamp, so it equals horizontal-then-vertical (up to the half-float round trip the two-pass version
+     * stores between passes). Used only for mips small enough that (2r+1)^2 taps cost less than a draw.
+     */
+    ensureBloomBlur2dProgram() {
+        if (this.bloomBlur2dProgram)
+            return this.bloomBlur2dProgram;
+        this.bloomBlur2dProgram = this.createFullscreenProgram(`#version 300 es
+precision highp float;
+precision highp int;
+uniform sampler2D u_source;
+uniform ivec2 u_size;
+uniform int u_radius;
+out vec4 outColor;
+
+vec4 sourcePixel(ivec2 coordinate) {
+  return texelFetch(u_source, clamp(coordinate, ivec2(0), u_size - ivec2(1)), 0);
+}
+
+void main() {
+  ivec2 pixel = ivec2(gl_FragCoord.xy);
+  float sigma = max(float(u_radius) / 3.0, 0.5);
+  float coefficient = 0.39894 / sigma;
+  // One-dimensional weights, identical to the separable pass.
+  float kernel[25];
+  float weightSum = coefficient;
+  kernel[0] = coefficient;
+  for (int offset = 1; offset <= 24; offset += 1) {
+    float distance = float(offset);
+    float weight = coefficient * exp(-0.5 * distance * distance / (sigma * sigma));
+    kernel[offset] = offset > u_radius ? 0.0 : weight;
+    if (offset <= u_radius) weightSum += 2.0 * weight;
+  }
+  weightSum = max(weightSum, 0.000001);
+  vec4 sum = vec4(0.0);
+  for (int dy = -24; dy <= 24; dy += 1) {
+    int ay = abs(dy);
+    if (ay > u_radius) continue;
+    float wy = kernel[ay];
+    for (int dx = -24; dx <= 24; dx += 1) {
+      int ax = abs(dx);
+      if (ax > u_radius) continue;
+      sum += sourcePixel(pixel + ivec2(dx, dy)) * (kernel[ax] * wy);
+    }
+  }
+  outColor = sum / (weightSum * weightSum);
+}
+`, "webgl2-bloom-blur-2d");
+        return this.bloomBlur2dProgram;
+    }
+    /** Weighted sum of up to five blurred mips, bilinearly upsampled to level-0 size, in one pass (smallest mip first, like the sequential accumulate). */
+    ensureBloomFusedAccumulateProgram() {
+        if (this.bloomFusedAccumulateProgram)
+            return this.bloomFusedAccumulateProgram;
+        this.bloomFusedAccumulateProgram = this.createFullscreenProgram(`#version 300 es
+precision highp float;
+uniform sampler2D u_mip0;
+uniform sampler2D u_mip1;
+uniform sampler2D u_mip2;
+uniform sampler2D u_mip3;
+uniform sampler2D u_mip4;
+uniform float u_weights[5];
+uniform int u_count;
+uniform vec2 u_targetSize;
+out vec4 outColor;
+void main() {
+  vec2 uv = gl_FragCoord.xy / u_targetSize;
+  vec3 sum = vec3(0.0);
+  if (u_count > 4) sum += texture(u_mip4, uv).rgb * u_weights[4];
+  if (u_count > 3) sum += texture(u_mip3, uv).rgb * u_weights[3];
+  if (u_count > 2) sum += texture(u_mip2, uv).rgb * u_weights[2];
+  if (u_count > 1) sum += texture(u_mip1, uv).rgb * u_weights[1];
+  sum += texture(u_mip0, uv).rgb * u_weights[0];
+  outColor = vec4(sum, 0.0);
+}
+`, "webgl2-bloom-fused-accumulate");
+        return this.bloomFusedAccumulateProgram;
+    }
+    /** HDR bloom composite that upsamples the level-0 accumulator itself (bilinear at the pixel centre) instead of reading a full-resolution copy. */
+    ensureBloomFusedCompositeProgram() {
+        if (this.bloomFusedCompositeProgram)
+            return this.bloomFusedCompositeProgram;
+        this.bloomFusedCompositeProgram = this.createFullscreenProgram(`#version 300 es
+precision highp float;
+precision highp int;
+uniform sampler2D u_source;
+uniform sampler2D u_blurred;
+uniform float u_intensity;
+out vec4 outColor;
+void main() {
+  ivec2 pixel = ivec2(gl_FragCoord.xy);
+  vec4 source = texelFetch(u_source, pixel, 0);
+  vec3 blurred = texture(u_blurred, gl_FragCoord.xy / vec2(textureSize(u_source, 0))).rgb;
+  outColor = vec4(source.rgb + blurred * u_intensity, source.a);
+}
+`, "webgl2-bloom-fused-composite");
+        return this.bloomFusedCompositeProgram;
+    }
+    /** Bright extract (HDR) + level-0 box downsample in one pass over an exactly 2:1 source; see `executeNativeBloomPyramidPasses`. */
+    ensureBloomPrefilterDownsampleProgram() {
+        if (this.bloomPrefilterDownsampleProgram)
+            return this.bloomPrefilterDownsampleProgram;
+        this.bloomPrefilterDownsampleProgram = this.createFullscreenProgram(`#version 300 es
+precision highp float;
+precision highp int;
+uniform sampler2D u_source;
+uniform float u_threshold;
+uniform float u_softKnee;
+uniform int u_excess;
+out vec4 outColor;
+vec4 a3dFinite(vec4 c) { return (any(isnan(c)) || any(isinf(c))) ? vec4(0.0) : c; }
+vec4 extractTexel(ivec2 pixel) {
+  vec4 source = texelFetch(u_source, pixel, 0);
+  float luma = dot(source.rgb, vec3(0.2126, 0.7152, 0.0722));
+  if (u_excess == 1) {
+    float knee = max(u_softKnee, 0.0);
+    float soft = clamp(luma - u_threshold + knee, 0.0, 2.0 * knee);
+    soft = soft * soft / (4.0 * knee + 1e-5);
+    float excessWeight = max(soft, luma - u_threshold) / max(luma, 1e-5);
+    return vec4(source.rgb * excessWeight, source.a);
+  }
+  float kneeLow = max(u_threshold - u_softKnee, 0.0);
+  float kneeHigh = min(u_threshold + u_softKnee, 1.0);
+  float weight = u_softKnee <= 0.0
+    ? (luma >= u_threshold ? 1.0 : 0.0)
+    : smoothstep(kneeLow, kneeHigh, luma);
+  return source * weight;
+}
+void main() {
+  ivec2 base = ivec2(gl_FragCoord.xy) * 2;
+  vec4 sum = a3dFinite(extractTexel(base)) + a3dFinite(extractTexel(base + ivec2(1, 0)))
+    + a3dFinite(extractTexel(base + ivec2(0, 1))) + a3dFinite(extractTexel(base + ivec2(1, 1)));
+  outColor = sum * 0.25;
+}
+`, "webgl2-bloom-prefilter-downsample");
+        return this.bloomPrefilterDownsampleProgram;
+    }
     ensureBloomAccumulateProgram() {
         if (this.bloomAccumulateProgram)
             return this.bloomAccumulateProgram;