@aura3d/engine 3.0.0 → 3.0.1

package/dist/rendering/Renderer.js

@@ -11,7 +11,7 @@ import {} from "./MorphTarget.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, volumetricLightPixels, writePostProcessPixels } from "./PostProcessPass.js";
-import { createRendererPostprocessPasses, createRendererPostprocessPlanDiagnostics } from "./RendererPostprocessPlan.js";
+import { bindRendererSsrProjection, createRendererPostprocessPasses, createRendererPostprocessPlanDiagnostics } from "./RendererPostprocessPlan.js";
 import { ShadowMap } from "./ShadowMap.js";
 import { ShadowPass } from "./ShadowPass.js";
 import { Sampler } from "./Sampler.js";
@@ -78,6 +78,10 @@ export class Renderer {
      * still reallocates exactly once.
      */
     shadowDepthTarget = null;
+    lastShadowEvidence = null;
+    submittedShadowFrameId = 0;
+    /** Actual shadow resources selected for the most recent submitted forward pass. */
+    getShadowEvidence() { return this.lastShadowEvidence; }
     /**
      * Forward-color target reused by the postprocess path across frames.
      *
@@ -94,8 +98,10 @@ export class Renderer {
     disposed = false;
     animationLoop = null;
     fusedLdrPostprocessScratch = {};
-    constructor(device, options) {
+    constructor(device, options, temporalHistory) {
         this.device = device;
+        this.temporalHistory = temporalHistory;
+        this.unsubscribeTemporalDeviceLoss = device.onDeviceLost?.(() => this.temporalHistory.dispose());
         this.canvas = options.canvas;
         this.width = options.width ?? inferInitialCanvasDimension(options.canvas, "width");
         this.height = options.height ?? inferInitialCanvasDimension(options.canvas, "height");
@@ -110,7 +116,11 @@ export class Renderer {
         }
         const shaderLibrary = options.shaderLibrary
             ?? (await import("./ShaderLibrary.js")).createDefaultShaderLibrary();
-        return new Renderer(device, { ...options, shaderLibrary });
+        // Temporal history is an optional runtime subsystem. Keep it behind the
+        // asynchronous renderer factory so non-temporal apps do not place its
+        // shaders, materials, and target owner on their critical download path.
+        const { TemporalHistory } = await import("./TemporalHistory.js");
+        return new Renderer(device, { ...options, shaderLibrary }, new TemporalHistory());
     }
     getFeatureReport() {
         return createRendererFeatureReport(this.device);
@@ -120,6 +130,8 @@ export class Renderer {
         if (width <= 0 || height <= 0 || !Number.isInteger(width) || !Number.isInteger(height)) {
             throw new RenderDeviceError("Renderer dimensions must be positive integers", "INVALID_FRAME_SIZE", { width, height });
         }
+        if (this.width !== width || this.height !== height)
+            this.temporalHistory.dispose();
         this.width = width;
         this.height = height;
         this.resizeCanvas(width, height);
@@ -155,6 +167,9 @@ export class Renderer {
         loop.start();
         return loop;
     }
+    temporalHistory;
+    unsubscribeTemporalDeviceLoss;
+    resetTemporalHistory(_reason = "explicit-reset") { this.temporalHistory.reset(); }
     render(sourceOrInput, camera) {
         this.assertAlive();
         const { source, camera: inputCamera } = normalizeRendererInput(sourceOrInput, camera);
@@ -190,7 +205,9 @@ export class Renderer {
                 cameraPosition = sourceCameraPosition ?? autoFrame.cameraPosition;
             }
         }
-        const postprocess = collectPostprocess(source);
+        let postprocess = collectPostprocess(source);
+        if (!postprocess?.temporal || (!postprocess.motionBlur && !postprocess.taa))
+            this.temporalHistory.reset();
         const ownedTargets = [];
         const ownedShadowPasses = [];
         this.graph.clear();
@@ -221,7 +238,10 @@ export class Renderer {
                     backend: this.device.kind
                 });
             }
-            const sampleCount = postprocess.sampleCount ?? (this.device.kind === "webgpu" && requiresDepthTexture ? 1 : 4);
+            // Temporal AA owns subpixel coverage. Pre-resolving MSAA before tone
+            // mapping gives it nonlinear mixed-coverage colors while velocity remains
+            // single-sample, biasing moving silhouettes and filtering them twice.
+            const sampleCount = postprocess.sampleCount ?? (postprocess.taa && postprocess.temporal ? 1 : 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.
@@ -231,6 +251,7 @@ export class Renderer {
         }
         this.device.beginFrame(this.width, this.height);
         try {
+            this.lastShadowEvidence = null;
             const rendererShadowMap = explicitShadowMap ?? this.executeRendererShadowMap({
                 shadowOptions,
                 source,
@@ -240,6 +261,14 @@ export class Renderer {
                 ownedShadowPasses,
                 camera: resolvedCamera?.camera
             });
+            this.lastShadowEvidence = rendererShadowMap ? {
+                lightMatrix: Array.from(rendererShadowMap.lightMatrix),
+                cascades: rendererShadowMap.cascades?.map(c => ({ index: c.index, near: c.near, far: c.far, lightMatrix: Array.from(c.shadowMap.lightMatrix) })) ?? [],
+                pointFaceMatrices: rendererShadowMap.pointLight ? Array.from(rendererShadowMap.pointLight.faceMatrices) : [],
+                pointFaceRects: rendererShadowMap.pointLight ? Array.from(rendererShadowMap.pointLight.faceRects) : [],
+                stabilize: shadowOptions?.stabilize !== false,
+                shadowRenderTargetsAllocated: this.device.getDiagnostics().shadowRenderTargetsAllocated ?? null,
+            } : null;
             if (postprocess) {
                 const forwardTarget = ownedTargets[0];
                 if (!forwardTarget) {
@@ -259,6 +288,14 @@ export class Renderer {
                     shaderLibrary: this.shaderLibrary
                 }));
             }
+            if (postprocess?.temporal && (postprocess.motionBlur || postprocess.taa)) {
+                if (postprocess.execution === "cpu-deterministic" || !this.device.presentLdrPostprocess)
+                    throw new RenderDeviceError("Renderer temporal effects require native GPU presentation", "TEMPORAL_NATIVE_REQUIRED");
+                const temporal = this.temporalHistory.prepare(this.device, this.width, this.height, items, cameraViewProjection, { ...postprocess.temporal, jitter: Boolean(postprocess.taa) });
+                items = this.temporalHistory.renderItems;
+                postprocess = { ...postprocess, ...(postprocess.motionBlur ? { motionBlur: { ...postprocess.motionBlur, temporal } } : {}), ...(postprocess.taa ? { taa: { ...postprocess.taa, temporal } } : {}) };
+                this.device.setRenderTarget(ownedTargets[0]);
+            }
             this.graph.addPass(new ForwardPass({
                 items,
                 lights,
@@ -274,9 +311,18 @@ export class Renderer {
             }));
             this.graph.execute({ device: this.device, width: this.width, height: this.height });
             if (postprocess) {
+                postprocess = bindRendererSsrProjection(postprocess, cameraViewProjection ?? identityMat4());
                 this.executePostprocess(postprocess, ownedTargets, explicitRenderTarget);
+                if (postprocess.temporal && (postprocess.motionBlur || postprocess.taa))
+                    this.temporalHistory.commit();
             }
         }
+        catch (error) {
+            this.lastShadowEvidence = null;
+            if (postprocess?.temporal)
+                this.temporalHistory.reset();
+            throw error;
+        }
         finally {
             this.device.endFrame();
             for (const shadowPass of ownedShadowPasses) {
@@ -290,6 +336,9 @@ export class Renderer {
                 target.dispose();
             }
         }
+        this.submittedShadowFrameId += 1;
+        if (this.lastShadowEvidence)
+            this.lastShadowEvidence = { ...this.lastShadowEvidence, submissionFrameId: this.submittedShadowFrameId };
         return withRendererFrameDiagnostics(this.device.getDiagnostics(), collectionDiagnostics, createPostprocessDiagnostics(postprocess, ownedTargets, this.width, this.height, {
             targetFormat: postprocessTargetFormat,
             nativeLdrPostprocess: Boolean(this.device.presentLdrPostprocess),
@@ -331,7 +380,9 @@ export class Renderer {
                 cameraPosition = sourceCameraPosition ?? autoFrame.cameraPosition;
             }
         }
-        const postprocess = collectPostprocess(source);
+        let postprocess = collectPostprocess(source);
+        if (!postprocess?.temporal || (!postprocess.motionBlur && !postprocess.taa))
+            this.temporalHistory.reset();
         const ownedTargets = [];
         const ownedShadowPasses = [];
         this.graph.clear();
@@ -362,7 +413,10 @@ export class Renderer {
                     backend: this.device.kind
                 });
             }
-            const sampleCount = postprocess.sampleCount ?? (this.device.kind === "webgpu" && requiresDepthTexture ? 1 : 4);
+            // Temporal AA owns subpixel coverage. Pre-resolving MSAA before tone
+            // mapping gives it nonlinear mixed-coverage colors while velocity remains
+            // single-sample, biasing moving silhouettes and filtering them twice.
+            const sampleCount = postprocess.sampleCount ?? (postprocess.taa && postprocess.temporal ? 1 : 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.
@@ -372,6 +426,7 @@ export class Renderer {
         }
         this.device.beginFrame(this.width, this.height);
         try {
+            this.lastShadowEvidence = null;
             const rendererShadowMap = explicitShadowMap ?? this.executeRendererShadowMap({
                 shadowOptions,
                 source,
@@ -381,6 +436,14 @@ export class Renderer {
                 ownedShadowPasses,
                 camera: resolvedCamera?.camera
             });
+            this.lastShadowEvidence = rendererShadowMap ? {
+                lightMatrix: Array.from(rendererShadowMap.lightMatrix),
+                cascades: rendererShadowMap.cascades?.map(c => ({ index: c.index, near: c.near, far: c.far, lightMatrix: Array.from(c.shadowMap.lightMatrix) })) ?? [],
+                pointFaceMatrices: rendererShadowMap.pointLight ? Array.from(rendererShadowMap.pointLight.faceMatrices) : [],
+                pointFaceRects: rendererShadowMap.pointLight ? Array.from(rendererShadowMap.pointLight.faceRects) : [],
+                stabilize: shadowOptions?.stabilize !== false,
+                shadowRenderTargetsAllocated: this.device.getDiagnostics().shadowRenderTargetsAllocated ?? null,
+            } : null;
             if (postprocess) {
                 const forwardTarget = ownedTargets[0];
                 if (!forwardTarget) {
@@ -400,6 +463,14 @@ export class Renderer {
                     shaderLibrary: this.shaderLibrary
                 }));
             }
+            if (postprocess?.temporal && (postprocess.motionBlur || postprocess.taa)) {
+                if (postprocess.execution === "cpu-deterministic" || !this.device.presentLdrPostprocess)
+                    throw new RenderDeviceError("Renderer temporal effects require native GPU presentation", "TEMPORAL_NATIVE_REQUIRED");
+                const temporal = this.temporalHistory.prepare(this.device, this.width, this.height, items, cameraViewProjection, { ...postprocess.temporal, jitter: Boolean(postprocess.taa) });
+                items = this.temporalHistory.renderItems;
+                postprocess = { ...postprocess, ...(postprocess.motionBlur ? { motionBlur: { ...postprocess.motionBlur, temporal } } : {}), ...(postprocess.taa ? { taa: { ...postprocess.taa, temporal } } : {}) };
+                this.device.setRenderTarget(ownedTargets[0]);
+            }
             this.graph.addPass(new ForwardPass({
                 items,
                 lights,
@@ -415,9 +486,18 @@ export class Renderer {
             }));
             this.graph.execute({ device: this.device, width: this.width, height: this.height });
             if (postprocess) {
+                postprocess = bindRendererSsrProjection(postprocess, cameraViewProjection ?? identityMat4());
                 await this.executePostprocessAsync(postprocess, ownedTargets, explicitRenderTarget);
+                if (postprocess.temporal && (postprocess.motionBlur || postprocess.taa))
+                    this.temporalHistory.commit();
             }
         }
+        catch (error) {
+            this.lastShadowEvidence = null;
+            if (postprocess?.temporal)
+                this.temporalHistory.reset();
+            throw error;
+        }
         finally {
             this.device.endFrame();
             for (const shadowPass of ownedShadowPasses) {
@@ -431,6 +511,9 @@ export class Renderer {
                 target.dispose();
             }
         }
+        this.submittedShadowFrameId += 1;
+        if (this.lastShadowEvidence)
+            this.lastShadowEvidence = { ...this.lastShadowEvidence, submissionFrameId: this.submittedShadowFrameId };
         return withRendererFrameDiagnostics(this.device.getDiagnostics(), collectionDiagnostics, createPostprocessDiagnostics(postprocess, ownedTargets, this.width, this.height, {
             targetFormat: postprocessTargetFormat,
             nativeLdrPostprocess: Boolean(this.device.presentLdrPostprocess),
@@ -465,12 +548,15 @@ export class Renderer {
         return this.device.getDiagnostics();
     }
     dispose() {
+        this.lastShadowEvidence = null;
         this.animationLoop?.stop();
         this.animationLoop = null;
         this.shadowDepthTarget?.dispose();
         this.shadowDepthTarget = null;
         this.forwardColorTarget?.target.dispose();
         this.forwardColorTarget = null;
+        this.unsubscribeTemporalDeviceLoss?.();
+        this.temporalHistory.dispose();
         this.device.dispose();
         this.disposed = true;
     }
@@ -990,7 +1076,7 @@ export class Renderer {
             casters: [],
             receivers: [],
             padding: options.shadowOptions.cascadePadding ?? 0.25,
-            stabilize: true
+            stabilize: options.shadowOptions.stabilize !== false
         });
         const lightMatrices = fits.map(shadowCameraFitViewProjectionMatrix);
         const cascadePass = new CascadedShadowPass({