@aura3d/engine 1.4.4 → 1.5.0

package/dist/rendering/Renderer.js

@@ -1,23 +1,27 @@
-import { Bounds3 as SceneBounds3, Camera, DirectionalLight, Light, PointLight, Scene, SpotLight, identityMat4, invertMat4, multiplyMat4, orthographicMat4, perspectiveMat4, transformPoint } from "../scene/index.js";
+import { Bounds3 as SceneBounds3, Camera, DirectionalLight, Light, PerspectiveCamera, PointLight, Scene, SpotLight, identityMat4, invertMat4, multiplyMat4, orthographicMat4, perspectiveMat4, transformPoint, toMathMat4 } from "../scene/index.js";
+import { Frustum } from "../math/index.js";
 import { createRenderDevice } from "./RenderBackend.js";
 import { RenderDeviceError } from "./RenderDevice.js";
 import { ENVIRONMENT_BACKGROUND_COLOR_RESOURCE, EnvironmentBackgroundPass } from "./EnvironmentBackgroundPass.js";
 import { ForwardPass } from "./ForwardPass.js";
+import { CascadedShadowMaps, CascadedShadowPass, shadowCameraFitViewProjectionMatrix } from "./CascadedShadowMaps.js";
 import { LightCollector } from "./LightCollector.js";
 import { Geometry } from "./Geometry.js";
 import {} from "./MorphTarget.js";
-import { computeSkinnedMorphTargetWeightedBounds } from "./SkinningBounds.js";
+import { computeSkinnedGeometryBounds, computeSkinnedMorphTargetWeightedBounds } from "./SkinningBounds.js";
 import { RenderGraph } from "./RenderGraph.js";
-import { BloomPass, FXAAPass, ToneMappingPass, bloomFloatPixels, bloomPixels, chromaticAberrationPixels, colorGradePixels, contactShadowPixels, createDepthTextureBinding, depthOfFieldPixels, filmGrainPixels, fusedLdrPostprocessPixels, fxaaPixels, motionBlurPixels, outlinePixels, ssaoPixels, ssrPixels, taaPixels, toneMapFloatPixels, toneMapPixels, writePostProcessPixels } from "./PostProcessPass.js";
+import { BloomPass, FXAAPass, ToneMappingPass, bloomFloatPixels, bloomPixels, chromaticAberrationPixels, colorGradePixels, contactShadowPixels, createDepthTextureBinding, depthOfFieldPixels, filmGrainPixels, fusedLdrPostprocessPixels, fxaaPixels, motionBlurPixels, outlinePixels, ssaoPixels, ssrPixels, taaPixels, toneMapFloatPixels, toneMapPixels, volumetricLightPixels, writePostProcessPixels } from "./PostProcessPass.js";
 import { createRendererPostprocessPasses, createRendererPostprocessPlanDiagnostics } from "./RendererPostprocessPlan.js";
 import { createDefaultShaderLibrary } from "./ShaderLibrary.js";
 import { ShadowMap } from "./ShadowMap.js";
 import { ShadowPass } from "./ShadowPass.js";
 import { Sampler } from "./Sampler.js";
+import {} from "./Texture.js";
 import { TextureBinding } from "./TextureBinding.js";
 import { computePerspectiveCameraFrame } from "./CameraFraming.js";
 import { assertRendererFeatures, createRendererFeatureReport } from "./RendererFeatureGates.js";
 import { batchStaticRenderItems } from "./SceneOptimization.js";
+import { createStaticMeshConsolidationCache } from "./MeshConsolidation.js";
 export const DEFAULT_RENDERER_AUTO_FRAME_OPTIONS = {
     paddingRatio: 0.14,
     yawRadians: -0.38,
@@ -67,6 +71,23 @@ export class Renderer {
     device;
     graph = new RenderGraph();
     shaderLibrary;
+    /**
+     * Depth target reused by the renderer-owned shadow pass across frames.
+     *
+     * A new `ShadowPass` is constructed per frame, so letting the pass own its target reallocated
+     * textures and re-ran `checkFramebufferStatus` every frame. Keyed by size so a shadow-size change
+     * still reallocates exactly once.
+     */
+    shadowDepthTarget = null;
+    /**
+     * Forward-color target reused by the postprocess path across frames.
+     *
+     * This was allocated fresh inside every `render()` call and pushed onto `ownedTargets`, which
+     * disposes it at end of frame. Creating a render target allocates textures and runs
+     * `checkFramebufferStatus` — both synchronous GPU operations — so an animating postprocess route
+     * paid a full target build-and-teardown every frame.
+     */
+    forwardColorTarget = null;
     canvas;
     width;
     height;
@@ -199,13 +220,11 @@ export class Renderer {
                     backend: this.device.kind
                 });
             }
-            const forwardTarget = this.device.createRenderTarget({
-                width: this.width,
-                height: this.height,
-                label: "renderer-forward-color",
-                format,
-                depth: requiresDepthTexture ? "texture" : true
-            });
+            const sampleCount = postprocess.sampleCount ?? (this.device.kind === "webgpu" && requiresDepthTexture ? 1 : 4);
+            // Reused across frames. It still occupies `ownedTargets[0]`, because the postprocess chain and
+            // the diagnostics builder both read the forward target from that slot; the end-of-frame
+            // disposal loop skips it via `isReusedTarget` so the reuse is safe.
+            const forwardTarget = this.ensureForwardColorTarget(format, requiresDepthTexture, sampleCount);
             ownedTargets.push(forwardTarget);
             this.device.setRenderTarget(forwardTarget);
         }
@@ -217,7 +236,8 @@ export class Renderer {
                 items,
                 lights,
                 ownedTargets,
-                ownedShadowPasses
+                ownedShadowPasses,
+                camera: resolvedCamera?.camera
             });
             if (postprocess) {
                 const forwardTarget = ownedTargets[0];
@@ -246,6 +266,8 @@ export class Renderer {
                 inputColorResource: environmentBackground ? ENVIRONMENT_BACKGROUND_COLOR_RESOURCE : undefined,
                 shadowMap: rendererShadowMap,
                 cameraPosition,
+                cameraViewMatrix: resolvedCamera?.viewMatrix,
+                cameraViewProjectionMatrix: cameraViewProjection,
                 outputColorSpace: postprocess ? "linear" : "srgb",
                 shaderLibrary: this.shaderLibrary
             }));
@@ -260,6 +282,10 @@ export class Renderer {
                 shadowPass.dispose();
             }
             for (const target of ownedTargets) {
+                // The reused forward-color target outlives the frame; disposing it here would reintroduce a
+                // per-frame allocation.
+                if (this.isReusedTarget(target))
+                    continue;
                 target.dispose();
             }
         }
@@ -335,13 +361,11 @@ export class Renderer {
                     backend: this.device.kind
                 });
             }
-            const forwardTarget = this.device.createRenderTarget({
-                width: this.width,
-                height: this.height,
-                label: "renderer-forward-color",
-                format,
-                depth: requiresDepthTexture ? "texture" : true
-            });
+            const sampleCount = postprocess.sampleCount ?? (this.device.kind === "webgpu" && requiresDepthTexture ? 1 : 4);
+            // Reused across frames. It still occupies `ownedTargets[0]`, because the postprocess chain and
+            // the diagnostics builder both read the forward target from that slot; the end-of-frame
+            // disposal loop skips it via `isReusedTarget` so the reuse is safe.
+            const forwardTarget = this.ensureForwardColorTarget(format, requiresDepthTexture, sampleCount);
             ownedTargets.push(forwardTarget);
             this.device.setRenderTarget(forwardTarget);
         }
@@ -353,7 +377,8 @@ export class Renderer {
                 items,
                 lights,
                 ownedTargets,
-                ownedShadowPasses
+                ownedShadowPasses,
+                camera: resolvedCamera?.camera
             });
             if (postprocess) {
                 const forwardTarget = ownedTargets[0];
@@ -382,6 +407,8 @@ export class Renderer {
                 inputColorResource: environmentBackground ? ENVIRONMENT_BACKGROUND_COLOR_RESOURCE : undefined,
                 shadowMap: rendererShadowMap,
                 cameraPosition,
+                cameraViewMatrix: resolvedCamera?.viewMatrix,
+                cameraViewProjectionMatrix: cameraViewProjection,
                 outputColorSpace: postprocess ? "linear" : "srgb",
                 shaderLibrary: this.shaderLibrary
             }));
@@ -396,6 +423,10 @@ export class Renderer {
                 shadowPass.dispose();
             }
             for (const target of ownedTargets) {
+                // The reused forward-color target outlives the frame; disposing it here would reintroduce a
+                // per-frame allocation.
+                if (this.isReusedTarget(target))
+                    continue;
                 target.dispose();
             }
         }
@@ -435,9 +466,51 @@ export class Renderer {
     dispose() {
         this.animationLoop?.stop();
         this.animationLoop = null;
+        this.shadowDepthTarget?.dispose();
+        this.shadowDepthTarget = null;
+        this.forwardColorTarget?.target.dispose();
+        this.forwardColorTarget = null;
         this.device.dispose();
         this.disposed = true;
     }
+    /** True for renderer-lifetime targets that must survive end-of-frame disposal. */
+    isReusedTarget(target) {
+        return target === this.forwardColorTarget?.target || target === this.shadowDepthTarget;
+    }
+    /** Allocates the shared forward-color target once per distinct configuration. */
+    ensureForwardColorTarget(format, requiresDepthTexture, sampleCount) {
+        const key = `${this.width}x${this.height}:${format}:${requiresDepthTexture ? "depth-texture" : "depth"}:${sampleCount}`;
+        const cached = this.forwardColorTarget;
+        if (cached && cached.key === key && !cached.target.disposed)
+            return cached.target;
+        cached?.target.dispose();
+        const target = this.device.createRenderTarget({
+            width: this.width,
+            height: this.height,
+            label: "renderer-forward-color",
+            format,
+            depth: requiresDepthTexture ? "texture" : true,
+            sampleCount
+        });
+        this.forwardColorTarget = { target, key };
+        return target;
+    }
+    /** Allocates the shared shadow depth target once, reallocating only when the size changes. */
+    ensureShadowDepthTarget(size) {
+        const existing = this.shadowDepthTarget;
+        if (existing && !existing.disposed && existing.width === size && existing.height === size)
+            return existing;
+        existing?.dispose();
+        const target = this.device.createRenderTarget({
+            width: size,
+            height: size,
+            label: "renderer-shadow-depth-color",
+            format: "rgba8",
+            depth: this.device.info.capabilities?.includes("depth-textures") ? "texture" : true
+        });
+        this.shadowDepthTarget = target;
+        return target;
+    }
     assertAlive() {
         if (this.disposed || this.device.disposed) {
             throw new RenderDeviceError("Renderer is disposed", "DISPOSED_DEVICE");
@@ -470,7 +543,7 @@ export class Renderer {
             }
             return;
         }
-        if (this.executeFusedLdrPostprocess(current, passes, outputTarget))
+        if (this.executeFusedLdrPostprocess(current, passes, outputTarget, postprocess.execution === "cpu-deterministic"))
             return;
         for (let index = 0; index < passes.length; index += 1) {
             const pass = passes[index];
@@ -542,10 +615,21 @@ export class Renderer {
                 current = target;
         }
     }
-    executeFusedLdrPostprocess(current, passes, outputTarget) {
+    executeFusedLdrPostprocess(current, passes, outputTarget, forceCpuDeterministic = false) {
         if (!canFuseLdrPostprocess(current, passes))
             return false;
-        if (this.device.presentLdrPostprocess) {
+        if (!forceCpuDeterministic && !this.device.presentLdrPostprocess && passes.some((pass) => pass.name === "depth-of-field" || pass.name === "motion-blur" || pass.name === "ssao" || pass.name === "ssr" || pass.name === "taa"))
+            return false;
+        // A caller that supplies its own `depth` array for depth-of-field/SSAO/SSR gets a plain
+        // depth renderbuffer, because `postprocessRequiresDepthTexture` only requests a
+        // sampleable depth texture when the renderer has to generate the depth itself. The
+        // backend's fused path samples `depthTextureHandle` regardless and used to throw
+        // `WEBGL_LDR_POSTPROCESS_DEPTH_REQUIRED`, failing the whole render rather than falling
+        // back. Declining fusion here routes those passes through the per-pass CPU path, which
+        // consumes the caller's depth directly and is the behaviour the options already imply.
+        if (!forceCpuDeterministic && !current.depthTexture && passes.some((pass) => pass.name === "depth-of-field" || pass.name === "ssao" || pass.name === "ssr"))
+            return false;
+        if (!forceCpuDeterministic && this.device.presentLdrPostprocess) {
             this.device.presentLdrPostprocess(current, {
                 passes: passes.map((pass) => ({
                     name: pass.name,
@@ -582,7 +666,7 @@ export class Renderer {
             }
             return;
         }
-        if (await this.executeFusedLdrPostprocessAsync(current, passes, outputTarget))
+        if (await this.executeFusedLdrPostprocessAsync(current, passes, outputTarget, postprocess.execution === "cpu-deterministic"))
             return;
         for (let index = 0; index < passes.length; index += 1) {
             const pass = passes[index];
@@ -651,10 +735,21 @@ export class Renderer {
                 current = target;
         }
     }
-    async executeFusedLdrPostprocessAsync(current, passes, outputTarget) {
+    async executeFusedLdrPostprocessAsync(current, passes, outputTarget, forceCpuDeterministic = false) {
         if (!canFuseLdrPostprocess(current, passes))
             return false;
-        if (this.device.presentLdrPostprocess) {
+        if (!forceCpuDeterministic && !this.device.presentLdrPostprocess && passes.some((pass) => pass.name === "depth-of-field" || pass.name === "motion-blur" || pass.name === "ssao" || pass.name === "ssr" || pass.name === "taa"))
+            return false;
+        // A caller that supplies its own `depth` array for depth-of-field/SSAO/SSR gets a plain
+        // depth renderbuffer, because `postprocessRequiresDepthTexture` only requests a
+        // sampleable depth texture when the renderer has to generate the depth itself. The
+        // backend's fused path samples `depthTextureHandle` regardless and used to throw
+        // `WEBGL_LDR_POSTPROCESS_DEPTH_REQUIRED`, failing the whole render rather than falling
+        // back. Declining fusion here routes those passes through the per-pass CPU path, which
+        // consumes the caller's depth directly and is the behaviour the options already imply.
+        if (!forceCpuDeterministic && !current.depthTexture && passes.some((pass) => pass.name === "depth-of-field" || pass.name === "ssao" || pass.name === "ssr"))
+            return false;
+        if (!forceCpuDeterministic && this.device.presentLdrPostprocess) {
             this.device.presentLdrPostprocess(current, {
                 passes: passes.map((pass) => ({
                     name: pass.name,
@@ -687,19 +782,21 @@ export class Renderer {
                     ? filmGrainPixels(input, source.width, source.height, pass.options).pixels
                     : pass.name === "depth-of-field"
                         ? depthOfFieldPixels(input, source.width, source.height, withRendererDepth(pass.options, rendererDepth)).pixels
-                        : pass.name === "motion-blur"
-                            ? motionBlurPixels(input, source.width, source.height, pass.options).pixels
-                            : pass.name === "contact-shadow"
-                                ? contactShadowPixels(input, source.width, source.height, withRendererDepth(pass.options, rendererDepth)).pixels
-                                : pass.name === "ssao"
-                                    ? ssaoPixels(input, source.width, source.height, withRendererDepth(pass.options, rendererDepth)).pixels
-                                    : pass.name === "ssr"
-                                        ? ssrPixels(input, source.width, source.height, withRendererDepth(pass.options, rendererDepth)).pixels
-                                        : pass.name === "taa"
-                                            ? taaPixels(input, source.width, source.height, pass.options).pixels
-                                            : pass.name === "outline"
-                                                ? outlinePixels(input, source.width, source.height, pass.options).pixels
-                                                : undefined;
+                        : pass.name === "volumetric-light"
+                            ? volumetricLightPixels(input, source.width, source.height, withRendererDepth(pass.options, rendererDepth)).pixels
+                            : pass.name === "motion-blur"
+                                ? motionBlurPixels(input, source.width, source.height, pass.options).pixels
+                                : pass.name === "contact-shadow"
+                                    ? contactShadowPixels(input, source.width, source.height, withRendererDepth(pass.options, rendererDepth)).pixels
+                                    : pass.name === "ssao"
+                                        ? ssaoPixels(input, source.width, source.height, withRendererDepth(pass.options, rendererDepth)).pixels
+                                        : pass.name === "ssr"
+                                            ? ssrPixels(input, source.width, source.height, withRendererDepth(pass.options, rendererDepth)).pixels
+                                            : pass.name === "taa"
+                                                ? taaPixels(input, source.width, source.height, pass.options).pixels
+                                                : pass.name === "outline"
+                                                    ? outlinePixels(input, source.width, source.height, pass.options).pixels
+                                                    : undefined;
         if (!result) {
             throw new RenderDeviceError("Renderer postprocess pass is outside the supported renderer pass catalog", "POSTPROCESS_PASS_UNKNOWN", {
                 pass: pass.name
@@ -720,19 +817,21 @@ export class Renderer {
                     ? filmGrainPixels(input, source.width, source.height, pass.options).pixels
                     : pass.name === "depth-of-field"
                         ? depthOfFieldPixels(input, source.width, source.height, withRendererDepth(pass.options, rendererDepth)).pixels
-                        : pass.name === "motion-blur"
-                            ? motionBlurPixels(input, source.width, source.height, pass.options).pixels
-                            : pass.name === "contact-shadow"
-                                ? contactShadowPixels(input, source.width, source.height, withRendererDepth(pass.options, rendererDepth)).pixels
-                                : pass.name === "ssao"
-                                    ? ssaoPixels(input, source.width, source.height, withRendererDepth(pass.options, rendererDepth)).pixels
-                                    : pass.name === "ssr"
-                                        ? ssrPixels(input, source.width, source.height, withRendererDepth(pass.options, rendererDepth)).pixels
-                                        : pass.name === "taa"
-                                            ? taaPixels(input, source.width, source.height, pass.options).pixels
-                                            : pass.name === "outline"
-                                                ? outlinePixels(input, source.width, source.height, pass.options).pixels
-                                                : undefined;
+                        : pass.name === "volumetric-light"
+                            ? volumetricLightPixels(input, source.width, source.height, withRendererDepth(pass.options, rendererDepth)).pixels
+                            : pass.name === "motion-blur"
+                                ? motionBlurPixels(input, source.width, source.height, pass.options).pixels
+                                : pass.name === "contact-shadow"
+                                    ? contactShadowPixels(input, source.width, source.height, withRendererDepth(pass.options, rendererDepth)).pixels
+                                    : pass.name === "ssao"
+                                        ? ssaoPixels(input, source.width, source.height, withRendererDepth(pass.options, rendererDepth)).pixels
+                                        : pass.name === "ssr"
+                                            ? ssrPixels(input, source.width, source.height, withRendererDepth(pass.options, rendererDepth)).pixels
+                                            : pass.name === "taa"
+                                                ? taaPixels(input, source.width, source.height, pass.options).pixels
+                                                : pass.name === "outline"
+                                                    ? outlinePixels(input, source.width, source.height, pass.options).pixels
+                                                    : undefined;
         if (!result) {
             throw new RenderDeviceError("Renderer postprocess pass is outside the supported renderer pass catalog", "POSTPROCESS_PASS_UNKNOWN", {
                 pass: pass.name
@@ -798,6 +897,17 @@ export class Renderer {
                 lightType: light.constructor.name
             });
         }
+        if (light instanceof DirectionalLight
+            && options.camera instanceof PerspectiveCamera
+            && (options.shadowOptions.cascadeCount ?? 1) > 1) {
+            return this.executeRendererCascadedShadowMap({
+                shadowOptions: options.shadowOptions,
+                items: options.items,
+                ownedShadowPasses: options.ownedShadowPasses,
+                light,
+                camera: options.camera
+            });
+        }
         const lightMatrix = options.shadowOptions.lightMatrix
             ? toMat4(options.shadowOptions.lightMatrix, "shadow.lightMatrix")
             : createRendererOwnedShadowMatrix(light, options.items, firstShadowCastingCollectedLight(options.lights));
@@ -815,7 +925,8 @@ export class Renderer {
             casters: options.items,
             shadowMap,
             viewProjectionMatrix: lightMatrix,
-            shaderLibrary: this.shaderLibrary
+            shaderLibrary: this.shaderLibrary,
+            renderTarget: this.ensureShadowDepthTarget(shadowMap.size)
         });
         options.ownedShadowPasses.push(shadowPass);
         const result = shadowPass.execute({ device: this.device, width: this.width, height: this.height });
@@ -836,6 +947,77 @@ export class Renderer {
             filterKernel: options.shadowOptions.filterKernel
         }) ?? undefined;
     }
+    executeRendererCascadedShadowMap(options) {
+        const cascadeCount = options.shadowOptions.cascadeCount ?? 4;
+        if (!Number.isInteger(cascadeCount) || cascadeCount < 2 || cascadeCount > 4) {
+            throw new RenderDeviceError("Renderer cascadeCount must be an integer in [2, 4].", "SHADOW_CASCADE_CONTRACT", { cascadeCount });
+        }
+        options.camera.transform.updateWorld(undefined, true);
+        const position = cameraWorldPosition(options.camera);
+        const world = options.camera.transform.worldMatrix;
+        const target = [
+            position[0] - (world[8] ?? 0),
+            position[1] - (world[9] ?? 0),
+            position[2] - (world[10] ?? 1)
+        ];
+        const cascades = new CascadedShadowMaps({
+            cascadeCount,
+            near: options.camera.near,
+            far: options.camera.far,
+            lambda: options.shadowOptions.cascadeLambda ?? 0.6,
+            size: options.shadowOptions.size,
+            bias: options.shadowOptions.bias,
+            filter: options.shadowOptions.filter,
+            pcfRadius: options.shadowOptions.pcfRadius,
+            pcfSamples: options.shadowOptions.pcfSamples,
+            label: options.shadowOptions.label ?? "renderer-csm"
+        });
+        const fits = cascades.computeStableCameraFits({
+            camera: {
+                position,
+                target,
+                fovYRadians: options.camera.fovYRadians,
+                aspect: options.camera.aspect
+            },
+            lightDirection: options.light.getDirection(),
+            casters: [],
+            receivers: [],
+            padding: options.shadowOptions.cascadePadding ?? 0.25,
+            stabilize: true
+        });
+        const lightMatrices = fits.map(shadowCameraFitViewProjectionMatrix);
+        const cascadePass = new CascadedShadowPass({
+            light: options.light,
+            casters: options.items,
+            cascades,
+            viewProjectionMatrices: lightMatrices,
+            shaderLibrary: this.shaderLibrary
+        });
+        const result = cascadePass.execute({ device: this.device, width: this.width, height: this.height });
+        options.ownedShadowPasses.push(cascadePass);
+        if (!result.rendered)
+            return undefined;
+        const maps = cascadePass.getForwardShadowMaps({
+            lightMatrices,
+            strength: options.shadowOptions.strength,
+            slopeBias: options.shadowOptions.slopeBias,
+            texelSize: options.shadowOptions.texelSize,
+            bias: options.shadowOptions.bias,
+            filterKernel: options.shadowOptions.filterKernel
+        });
+        const first = maps[0];
+        if (!first || maps.length !== result.cascades.length)
+            return undefined;
+        return {
+            ...first,
+            cascades: result.cascades.map((cascade, index) => ({
+                index: cascade.index,
+                near: cascade.split.near,
+                far: cascade.split.far,
+                shadowMap: maps[index]
+            }))
+        };
+    }
     executeRendererPointShadowMap(options) {
         if (!this.device.writeRenderTargetPixels) {
             throw new RenderDeviceError("Renderer-owned point shadows require render-target pixel upload for the point-light atlas.", "POINT_SHADOW_ATLAS_UPLOAD_UNSUPPORTED", {
@@ -1230,7 +1412,7 @@ function lookAtMatrix(eye, target, up) {
     ];
 }
 function createDirectionalShadowMatrix(items, lightDirection) {
-    const bounds = collectRenderItemBounds(items);
+    const bounds = collectShadowCoverageBounds(items);
     if (!bounds || bounds.isEmpty()) {
         return identityMat4();
     }
@@ -1344,7 +1526,8 @@ function collectCameraPolicy(source) {
     return "identity";
 }
 function postprocessRequiresDepthTexture(postprocess) {
-    return Boolean((postprocess.depthOfField && !postprocess.depthOfField.depth) ||
+    return Boolean((postprocess.volumetricLight && !postprocess.volumetricLight.depth) ||
+        (postprocess.depthOfField && !postprocess.depthOfField.depth) ||
         (postprocess.contactShadow && !postprocess.contactShadow.depth) ||
         (postprocess.ssao && !postprocess.ssao.depth) ||
         (postprocess.ssr && !postprocess.ssr.depth));
@@ -1353,23 +1536,37 @@ function canFuseLdrPostprocess(source, passes) {
     const sourceIsHdr = isHdrRenderTarget(source);
     return passes.length > 1
         && (!sourceIsHdr || passes[0]?.name === "tone-mapping")
-        && passes.every((pass) => pass.name === "tone-mapping" || pass.name === "color-grade" || pass.name === "fxaa")
+        && passes.every((pass) => pass.name === "bloom" || pass.name === "tone-mapping" || pass.name === "color-grade" || pass.name === "depth-of-field" || pass.name === "motion-blur" || pass.name === "ssao" || pass.name === "ssr" || pass.name === "taa" || pass.name === "outline" || pass.name === "fxaa")
         && passes.every((pass, index) => {
             const previousRank = index === 0 ? -1 : ldrFusionPassRank(passes[index - 1].name);
             return ldrFusionPassRank(pass.name) >= previousRank;
         });
 }
 function ldrFusionPassRank(name) {
+    if (name === "bloom")
+        return -1;
     if (name === "tone-mapping")
         return 0;
     if (name === "color-grade")
         return 1;
-    if (name === "fxaa")
+    if (name === "depth-of-field")
         return 2;
+    if (name === "motion-blur")
+        return 3;
+    if (name === "ssao")
+        return 4;
+    if (name === "ssr")
+        return 5;
+    if (name === "taa")
+        return 6;
+    if (name === "outline")
+        return 7;
+    if (name === "fxaa")
+        return 8;
     return Number.POSITIVE_INFINITY;
 }
 function isDepthPostprocessPass(name) {
-    return name === "depth-of-field" || name === "contact-shadow" || name === "ssao" || name === "ssr";
+    return name === "volumetric-light" || name === "depth-of-field" || name === "contact-shadow" || name === "ssao" || name === "ssr";
 }
 function postprocessPassHasDepth(options) {
     return typeof options === "object" && options !== null && "depth" in options && Boolean(options.depth);
@@ -1425,17 +1622,142 @@ function collectRenderItemsWithDiagnostics(source, cameraViewProjection, camera)
         explicitItems.push(...source.renderItems);
     }
     if (explicitItems.length > 0) {
-        const optimizedItems = applyRendererOwnedStaticBatching(source, explicitItems);
+        const cullingFrustum = explicitCullingFrustum(source, cameraViewProjection, camera);
+        const visibleItems = cullExplicitRenderItems(explicitItems, cullingFrustum, diagnostics);
+        const optimizedItems = applyRendererOwnedStaticBatching(source, applyRendererOwnedStaticMeshConsolidation(source, visibleItems));
         const projectedItems = applyViewProjection(optimizedItems, cameraViewProjection);
-        diagnostics.submittedObjects += explicitItems.length;
-        diagnostics.visibleObjects += explicitItems.length;
         items.push(...projectedItems);
     }
     return { items, diagnostics };
 }
+function explicitCullingFrustum(source, cameraViewProjection, camera) {
+    // Explicit render-item sources were historically never culled, so culling
+    // stays opt-in: only an explicit `frustumCulling: true` turns it on.
+    if (source.frustumCulling !== true)
+        return undefined;
+    if (camera)
+        return camera.frustum;
+    if (!cameraViewProjection)
+        return undefined;
+    return Frustum.fromMatrix(toMathMat4(cameraViewProjection));
+}
+function cullExplicitRenderItems(items, frustum, diagnostics) {
+    if (!frustum) {
+        diagnostics.submittedObjects += items.length;
+        diagnostics.visibleObjects += items.length;
+        return items;
+    }
+    const visible = [];
+    for (const item of items) {
+        diagnostics.submittedObjects += 1;
+        if (!isFrustumCullableRenderItem(item)) {
+            diagnostics.visibleObjects += 1;
+            visible.push(item);
+            continue;
+        }
+        diagnostics.frustumTestedObjects += 1;
+        const bounds = explicitRenderItemWorldBounds(item);
+        if (!frustum.intersectsBox(bounds.toMathBox())) {
+            diagnostics.culledObjects += 1;
+            continue;
+        }
+        diagnostics.visibleObjects += 1;
+        visible.push(item);
+    }
+    return visible;
+}
+function isFrustumCullableRenderItem(item) {
+    if (item.drawRange !== undefined)
+        return false;
+    if (item.morphTargets !== undefined || item.morphWeights !== undefined)
+        return false;
+    return true;
+}
+function explicitRenderItemWorldBounds(item) {
+    const modelMatrix = toMat4(item.modelMatrix ?? identityMat4(), "modelMatrix", item.label);
+    if (item.skinning) {
+        const local = skinnedItemLocalBounds(item.geometry, item.skinning);
+        return boundsFromLocal(local, modelMatrix, item.instanceTransforms);
+    }
+    return boundsFromLocal(item.geometry.bounds, modelMatrix, item.instanceTransforms);
+}
+function boundsFromLocal(envelope, modelMatrix, instanceTransforms) {
+    const local = new SceneBounds3([envelope.min[0], envelope.min[1], envelope.min[2]], [envelope.max[0], envelope.max[1], envelope.max[2]]);
+    if (!instanceTransforms || instanceTransforms.length < 16) {
+        return local.transform(modelMatrix);
+    }
+    let bounds = new SceneBounds3();
+    for (let offset = 0; offset + 16 <= instanceTransforms.length; offset += 16) {
+        const instanceMatrix = toMat4(instanceTransforms.slice(offset, offset + 16), "instanceTransforms");
+        bounds = bounds.union(local.transform(multiplyMat4(modelMatrix, instanceMatrix)));
+    }
+    return bounds;
+}
+const skinnedCullingBoundsCache = new WeakMap();
+function skinnedItemLocalBounds(geometry, skinning) {
+    const cached = skinnedCullingBoundsCache.get(geometry);
+    if (cached && float32ArraysEqual(cached.matrices, skinning.matrices)) {
+        return cached.bounds;
+    }
+    const bounds = computeSkinnedGeometryBounds(geometry, skinning);
+    skinnedCullingBoundsCache.set(geometry, { matrices: new Float32Array(skinning.matrices), bounds });
+    return bounds;
+}
+function float32ArraysEqual(left, right) {
+    if (left.length !== right.length)
+        return false;
+    for (let index = 0; index < left.length; index += 1) {
+        if (left[index] !== right[index])
+            return false;
+    }
+    return true;
+}
 const staticBatchGeometryIds = new WeakMap();
 const staticBatchMaterialIds = new WeakMap();
 let nextStaticBatchResourceId = 1;
+/**
+ * Merges shared-material static geometry, then hands the result to batching.
+ *
+ * Consolidation runs first because it reduces distinct geometries; whatever it leaves unmerged (single
+ * items, oversized meshes, non-indexed topology) can still be instanced by batching afterwards.
+ */
+const staticMeshConsolidationCaches = new WeakMap();
+function applyRendererOwnedStaticMeshConsolidation(source, items) {
+    if (!source.staticMeshConsolidation)
+        return items;
+    const mergeable = [];
+    const passthrough = [];
+    for (const item of items) {
+        // The same eligibility rule as batching: anything skinned, morphed, instanced, or draw-ranged is
+        // not static geometry and must not have a transform baked into it.
+        if (isStaticBatchCandidate(item)) {
+            mergeable.push({
+                geometry: item.geometry,
+                material: item.material,
+                modelMatrix: item.modelMatrix ?? identityMat4(),
+                ...(item.label ? { label: item.label } : {})
+            });
+        }
+        else {
+            passthrough.push(item);
+        }
+    }
+    if (mergeable.length === 0)
+        return items;
+    const options = source.staticMeshConsolidation === true ? {} : source.staticMeshConsolidation;
+    // Cached per render source: merging walks every vertex, so repeating it each frame costs far more
+    // than the draw calls it saves.
+    let cache = staticMeshConsolidationCaches.get(source);
+    if (!cache) {
+        cache = createStaticMeshConsolidationCache();
+        staticMeshConsolidationCaches.set(source, cache);
+    }
+    const consolidated = cache.consolidate(mergeable, {
+        labelPrefix: "renderer-consolidated-mesh",
+        ...options
+    });
+    return [...passthrough, ...consolidated.renderItems];
+}
 function applyRendererOwnedStaticBatching(source, items) {
     if (!source.staticBatching)
         return items;
@@ -1883,9 +2205,26 @@ function createAutoFrameCamera(source, items, width, height) {
     };
 }
 function collectRenderItemBounds(items) {
+    return collectItemBounds(items, true);
+}
+/**
+ * Bounds over every render item, including those excluded from camera
+ * auto-framing.
+ *
+ * `includeInAutoFrame` answers "should the camera frame this?", which is a
+ * composition choice. It must not decide which geometry a shadow frustum covers:
+ * a large ground plane or backdrop is commonly excluded from auto-framing while
+ * still being the surface that receives shadows. Fitting the light frustum to the
+ * auto-frame subset shrinks it to the caster alone, so the receiver falls outside
+ * the shadow map and no shadow is ever visible.
+ */
+function collectShadowCoverageBounds(items) {
+    return collectItemBounds(items, false);
+}
+function collectItemBounds(items, respectAutoFrameExclusion) {
     let bounds;
     for (const item of items) {
-        if (item.includeInAutoFrame === false)
+        if (respectAutoFrameExclusion && item.includeInAutoFrame === false)
             continue;
         const itemBounds = renderableWorldBounds(item.geometry, toMat4(item.modelMatrix ?? identityMat4(), "modelMatrix", item.label), item.instanceTransforms, item.morphTargets, item.morphWeights, item.skinning);
         bounds = bounds ? bounds.union(itemBounds) : itemBounds;
@@ -1932,6 +2271,7 @@ function resolveCamera(source, camera, viewport, options = {}) {
         const viewMatrix = resolved.viewMatrix ? toMat4(resolved.viewMatrix, "viewMatrix") : undefined;
         return {
             viewProjectionMatrix: toMat4(resolved.viewProjectionMatrix, "viewProjectionMatrix"),
+            ...(viewMatrix ? { viewMatrix } : {}),
             ...(resolved instanceof Camera
                 ? { camera: resolved, cameraPosition: cameraWorldPosition(resolved) }
                 : viewMatrix
@@ -1943,6 +2283,7 @@ function resolveCamera(source, camera, viewport, options = {}) {
         const viewMatrix = toMat4(resolved.viewMatrix, "viewMatrix");
         return {
             viewProjectionMatrix: multiplyMat4(toMat4(resolved.projectionMatrix, "projectionMatrix"), viewMatrix),
+            viewMatrix,
             ...(resolved instanceof Camera
                 ? { camera: resolved, cameraPosition: cameraWorldPosition(resolved) }
                 : { cameraPosition: cameraPositionFromViewMatrix(viewMatrix) })
@@ -2052,7 +2393,11 @@ function createDefaultRendererDirectLights() {
             intensity: light.intensity,
             position: [0, 0, 0],
             direction: normalizeDefaultLightDirection(light.direction),
+            right: [1, 0, 0],
+            up: [0, 1, 0],
             range: 0,
+            width: 0,
+            height: 0,
             spotAngle: 0,
             penumbra: 0,
             castsShadow: false,