FrameGraph: adds support for frozen meshes + allows no output color texture for the geometry buffer renderer task (#17040)

This PR adds support for frozen meshes to frame graphs.

Note that we have a bug when using multiple active cameras in a scene
with meshes + instances. If we freeze the scene, only some instances
(those that were culled and displayed by the last camera in the list)
are displayed, due to the way we currently handle frozen meshes (we have
a single `scene._activeMeshes` list, which is populated by a call to
`_evaluateActiveMeshes` when `freezeActiveMeshes` is called). I'm not
sure how to fix this bug in the current code, but the frame graph
version of the same example works correctly because it uses object
renderers to render meshes:
* without frame graph: https://playground.babylonjs.com/#9SDNZF#30
* with frame graph: https://playground.babylonjs.com/#9SDNZF#29

The meshes are frozen after two seconds. In the first PG, some instances
disappear along with the plane because they are displayed by the first
camera. Note that you must wait for the PR to be merged to test the
second PG, because otherwise the meshes will not be frozen even after
calling `scene.freezeActiveMeshes()`!

In addition, the PR allows you to not define any output color textures
for the geometry buffer renderer. This allows you to generate only a
depth render of the scene and reuse the depth buffer when rendering the
scene later in the graph.

Author: Popov72

packages/dev/core/src/Engines/Extensions/engine.multiRender.ts

@@ -63,9 +63,10 @@ declare module "../../Engines/abstractEngine" {
         /**
          * Creates a layout object to draw/clear on specific textures in a MRT
          * @param textureStatus textureStatus[i] indicates if the i-th is active
+         * @param backBufferLayout if true, the layout will be built to account for the back buffer only, and textureStatus won't be used
          * @returns A layout to be fed to the engine, calling `bindAttachments`.
          */
-        buildTextureLayout(textureStatus: boolean[]): number[];
+        buildTextureLayout(textureStatus: boolean[], backBufferLayout?: boolean): number[];
 
         /**
          * Restores the webgl state to only draw on the main color attachment
@@ -93,16 +94,20 @@ ThinEngine.prototype.restoreSingleAttachmentForRenderTarget = function (): void
     this.bindAttachments([gl.COLOR_ATTACHMENT0]);
 };
 
-ThinEngine.prototype.buildTextureLayout = function (textureStatus: boolean[]): number[] {
+ThinEngine.prototype.buildTextureLayout = function (textureStatus: boolean[], backBufferLayout = false): number[] {
     const gl = this._gl;
 
     const result = [];
 
-    for (let i = 0; i < textureStatus.length; i++) {
-        if (textureStatus[i]) {
-            result.push((<any>gl)["COLOR_ATTACHMENT" + i]);
-        } else {
-            result.push(gl.NONE);
+    if (backBufferLayout) {
+        result.push(gl.BACK);
+    } else {
+        for (let i = 0; i < textureStatus.length; i++) {
+            if (textureStatus[i]) {
+                result.push((<any>gl)["COLOR_ATTACHMENT" + i]);
+            } else {
+                result.push(gl.NONE);
+            }
         }
     }
 

packages/dev/core/src/Engines/WebGPU/Extensions/engine.multiRender.ts

@@ -62,9 +62,10 @@ declare module "../../abstractEngine" {
         /**
          * Creates a layout object to draw/clear on specific textures in a MRT
          * @param textureStatus textureStatus[i] indicates if the i-th is active
+         * @param backBufferLayout if true, the layout will be built to account for the back buffer only, and textureStatus won't be used
          * @returns A layout to be fed to the engine, calling `bindAttachments`.
          */
-        buildTextureLayout(textureStatus: boolean[]): number[];
+        buildTextureLayout(textureStatus: boolean[], backBufferLayout?: boolean): number[];
 
         /**
          * Restores the webgl state to only draw on the main color attachment
@@ -356,14 +357,18 @@ WebGPUEngine.prototype.bindAttachments = function (attachments: number[]): void
     }
 };
 
-WebGPUEngine.prototype.buildTextureLayout = function (textureStatus: boolean[]): number[] {
+WebGPUEngine.prototype.buildTextureLayout = function (textureStatus: boolean[], backBufferLayout = false): number[] {
     const result = [];
 
-    for (let i = 0; i < textureStatus.length; i++) {
-        if (textureStatus[i]) {
-            result.push(i + 1);
-        } else {
-            result.push(0);
+    if (backBufferLayout) {
+        result.push(1);
+    } else {
+        for (let i = 0; i < textureStatus.length; i++) {
+            if (textureStatus[i]) {
+                result.push(i + 1);
+            } else {
+                result.push(0);
+            }
         }
     }
 

packages/dev/core/src/Engines/WebGPU/webgpuDrawContext.ts

@@ -25,6 +25,13 @@ export class WebGPUDrawContext implements IDrawContext {
 
     public uniqueId: number;
 
+    /**
+     * @internal
+     * By default, indirect draws are enabled in NON compatibility mode only
+     * To enable indirect draws in compatibility mode (done by the end user), enableIndirectDraw must be set to true
+     */
+    public _enableIndirectDrawInCompatMode = false;
+
     /**
      * Buffers (uniform / storage) used for the draw call
      */
@@ -64,6 +71,8 @@ export class WebGPUDrawContext implements IDrawContext {
     }
 
     public set enableIndirectDraw(enable: boolean) {
+        this._enableIndirectDrawInCompatMode = true;
+
         if (this._enableIndirectDraw === enable) {
             return;
         }
@@ -99,7 +108,11 @@ export class WebGPUDrawContext implements IDrawContext {
         this._useInstancing = use;
         this._currentInstanceCount = -1;
 
+        const enableIndirectDrawInCompatMode = this._enableIndirectDrawInCompatMode;
+
         this.enableIndirectDraw = use;
+
+        this._enableIndirectDrawInCompatMode = enableIndirectDrawInCompatMode;
     }
 
     /**

packages/dev/core/src/Engines/webgpuEngine.ts

@@ -3775,7 +3775,7 @@ export class WebGPUEngine extends ThinWebGPUEngine {
         // draw
         const nonCompatMode = !this.compatibilityMode && !this._snapshotRendering.record;
 
-        if (this._currentDrawContext.indirectDrawBuffer) {
+        if ((nonCompatMode || this._currentDrawContext._enableIndirectDrawInCompatMode) && this._currentDrawContext.indirectDrawBuffer) {
             this._currentDrawContext.setIndirectData(count, instancesCount || 1, start);
             if (drawType === 0) {
                 renderPass2.drawIndexedIndirect(this._currentDrawContext.indirectDrawBuffer, 0);

packages/dev/core/src/FrameGraph/Node/Blocks/Rendering/baseObjectRendererBlock.ts

@@ -100,6 +100,46 @@ export class NodeRenderGraphBaseObjectRendererBlock extends NodeRenderGraphBlock
         this._frameGraphTask.depthWrite = value;
     }
 
+    /** Indicates if particles should be rendered */
+    @editableInPropertyPage("Render particles", PropertyTypeForEdition.Boolean, "PROPERTIES")
+    public get renderParticles() {
+        return this._frameGraphTask.renderParticles;
+    }
+
+    public set renderParticles(value: boolean) {
+        this._frameGraphTask.renderParticles = value;
+    }
+
+    /** Indicates if sprites should be rendered */
+    @editableInPropertyPage("Render sprites", PropertyTypeForEdition.Boolean, "PROPERTIES")
+    public get renderSprites() {
+        return this._frameGraphTask.renderSprites;
+    }
+
+    public set renderSprites(value: boolean) {
+        this._frameGraphTask.renderSprites = value;
+    }
+
+    /** Indicates if layer mask check must be forced */
+    @editableInPropertyPage("Force layer mask check", PropertyTypeForEdition.Boolean, "PROPERTIES")
+    public get forceLayerMaskCheck() {
+        return this._frameGraphTask.forceLayerMaskCheck;
+    }
+
+    public set forceLayerMaskCheck(value: boolean) {
+        this._frameGraphTask.forceLayerMaskCheck = value;
+    }
+
+    /** Indicates if bounding boxes should be rendered */
+    @editableInPropertyPage("Enable bounding box rendering", PropertyTypeForEdition.Boolean, "PROPERTIES")
+    public get enableBoundingBoxRendering() {
+        return this._frameGraphTask.enableBoundingBoxRendering;
+    }
+
+    public set enableBoundingBoxRendering(value: boolean) {
+        this._frameGraphTask.enableBoundingBoxRendering = value;
+    }
+
     /** Indicates if shadows must be enabled or disabled */
     @editableInPropertyPage("Disable shadows", PropertyTypeForEdition.Boolean, "PROPERTIES")
     public get disableShadows() {
@@ -224,6 +264,10 @@ export class NodeRenderGraphBaseObjectRendererBlock extends NodeRenderGraphBlock
         const codes: string[] = [];
         codes.push(`${this._codeVariableName}.depthTest = ${this.depthTest};`);
         codes.push(`${this._codeVariableName}.depthWrite = ${this.depthWrite};`);
+        codes.push(`${this._codeVariableName}.renderParticles = ${this.renderParticles};`);
+        codes.push(`${this._codeVariableName}.renderSprites = ${this.renderSprites};`);
+        codes.push(`${this._codeVariableName}.forceLayerMaskCheck = ${this.forceLayerMaskCheck};`);
+        codes.push(`${this._codeVariableName}.enableBoundingBoxRendering = ${this.enableBoundingBoxRendering};`);
         codes.push(`${this._codeVariableName}.disableShadows = ${this.disableShadows};`);
         codes.push(`${this._codeVariableName}.renderInLinearSpace = ${this.renderInLinearSpace};`);
         codes.push(`${this._codeVariableName}.isMainObjectRenderer = ${this.isMainObjectRenderer};`);
@@ -234,6 +278,10 @@ export class NodeRenderGraphBaseObjectRendererBlock extends NodeRenderGraphBlock
         const serializationObject = super.serialize();
         serializationObject.depthTest = this.depthTest;
         serializationObject.depthWrite = this.depthWrite;
+        serializationObject.renderParticles = this.renderParticles;
+        serializationObject.renderSprites = this.renderSprites;
+        serializationObject.forceLayerMaskCheck = this.forceLayerMaskCheck;
+        serializationObject.enableBoundingBoxRendering = this.enableBoundingBoxRendering;
         serializationObject.disableShadows = this.disableShadows;
         serializationObject.renderInLinearSpace = this.renderInLinearSpace;
         serializationObject.isMainObjectRenderer = this.isMainObjectRenderer;
@@ -244,6 +292,10 @@ export class NodeRenderGraphBaseObjectRendererBlock extends NodeRenderGraphBlock
         super._deserialize(serializationObject);
         this.depthTest = serializationObject.depthTest;
         this.depthWrite = serializationObject.depthWrite;
+        this.renderParticles = serializationObject.renderParticles ?? true;
+        this.renderSprites = serializationObject.renderSprites ?? true;
+        this.forceLayerMaskCheck = serializationObject.forceLayerMaskCheck ?? true;
+        this.enableBoundingBoxRendering = serializationObject.enableBoundingBoxRendering ?? true;
         this.disableShadows = serializationObject.disableShadows;
         this.renderInLinearSpace = !!serializationObject.renderInLinearSpace;
         this.isMainObjectRenderer = !!serializationObject.isMainObjectRenderer;

packages/dev/core/src/FrameGraph/Node/Blocks/Rendering/geometryRendererBlock.ts

@@ -377,10 +377,6 @@ export class NodeRenderGraphGeometryRendererBlock extends NodeRenderGraphBlock {
             this.geomLinearVelocity.isConnected,
         ];
 
-        if (textureActivation.every((t) => !t)) {
-            throw new Error("NodeRenderGraphGeometryRendererBlock: At least one output geometry buffer must be connected");
-        }
-
         this.outputDepth.value = this._frameGraphTask.outputDepthTexture;
         this.geomViewDepth.value = this._frameGraphTask.geometryViewDepthTexture;
         this.geomNormViewDepth.value = this._frameGraphTask.geometryNormViewDepthTexture;

packages/dev/core/src/FrameGraph/Node/nodeRenderGraph.ts

@@ -26,6 +26,7 @@ import { NodeRenderGraphBlockConnectionPointTypes } from "./Types/nodeRenderGrap
 import { NodeRenderGraphClearBlock } from "./Blocks/Textures/clearBlock";
 import { NodeRenderGraphObjectRendererBlock } from "./Blocks/Rendering/objectRendererBlock";
 import { NodeRenderGraphBuildState } from "./nodeRenderGraphBuildState";
+import { NodeRenderGraphCullObjectsBlock } from "./Blocks/cullObjectsBlock";
 
 // declare NODERENDERGRAPHEDITOR namespace for compilation issue
 // eslint-disable-next-line @typescript-eslint/naming-convention
@@ -625,14 +626,19 @@ export class NodeRenderGraph {
         colorTexture.output.connectTo(clear.target);
         depthTexture.output.connectTo(clear.depth);
 
-        // Render objects
+        // Object list and culling
         const camera = new NodeRenderGraphInputBlock("Camera", this._frameGraph, this._scene, NodeRenderGraphBlockConnectionPointTypes.Camera);
         const objectList = new NodeRenderGraphInputBlock("Object List", this._frameGraph, this._scene, NodeRenderGraphBlockConnectionPointTypes.ObjectList);
+        const cull = new NodeRenderGraphCullObjectsBlock("Cull", this._frameGraph, this._scene);
+
+        camera.output.connectTo(cull.camera);
+        objectList.output.connectTo(cull.objects);
 
+        // Render objects
         const mainRendering = new NodeRenderGraphObjectRendererBlock("Main Rendering", this._frameGraph, this._scene);
 
         camera.output.connectTo(mainRendering.camera);
-        objectList.output.connectTo(mainRendering.objects);
+        cull.output.connectTo(mainRendering.objects);
         clear.output.connectTo(mainRendering.target);
         clear.outputDepth.connectTo(mainRendering.depth);
 

packages/dev/core/src/FrameGraph/Tasks/Layers/baseLayerTask.ts

@@ -371,7 +371,7 @@ export class FrameGraphBaseLayerTask extends FrameGraphTask {
                         if (
                             !this.layer.shouldRender() ||
                             info.renderingGroupId !== this.layer._options.renderingGroupId ||
-                            info.renderingManager !== this.objectRendererTask.objectRenderer._renderingManager
+                            info.renderingManager !== this.objectRendererTask.objectRenderer.renderingManager
                         ) {
                             return;
                         }

packages/dev/core/src/FrameGraph/Tasks/Misc/cullObjectsTask.ts

@@ -32,8 +32,8 @@ export class FrameGraphCullObjectsTask extends FrameGraphTask {
         super(name, frameGraph);
         this._scene = scene;
         this.outputObjectList = {
-            meshes: [],
-            particleSystems: [],
+            meshes: null,
+            particleSystems: null,
         };
     }
 
@@ -42,10 +42,22 @@ export class FrameGraphCullObjectsTask extends FrameGraphTask {
             throw new Error(`FrameGraphCullObjectsTask ${this.name}: objectList and camera are required`);
         }
 
+        // Initial output values
+        this.outputObjectList.meshes = this.objectList.meshes;
+        this.outputObjectList.particleSystems = this.objectList.particleSystems;
+
         const pass = this._frameGraph.addCullPass(this.name);
 
         pass.setObjectList(this.outputObjectList);
         pass.setExecuteFunc((_context) => {
+            // No culling on particle systems
+            this.outputObjectList.particleSystems = this.objectList.particleSystems;
+
+            if (this._scene._activeMeshesFrozen) {
+                // If active meshes are frozen, we don't need culling: we keep the last list created before freezing
+                return;
+            }
+
             this.outputObjectList.meshes = [];
 
             this.camera._updateFrustumPlanes();

packages/dev/core/src/FrameGraph/Tasks/Rendering/geometryRendererTask.ts

@@ -300,8 +300,8 @@ export class FrameGraphGeometryRendererTask extends FrameGraphTask {
     }
 
     public record() {
-        if (this.textureDescriptions.length === 0 || this.objectList === undefined) {
-            throw new Error(`FrameGraphGeometryRendererTask ${this.name}: object list and at least one geometry texture description must be provided`);
+        if (this.objectList === undefined) {
+            throw new Error(`FrameGraphGeometryRendererTask ${this.name}: object list must be provided`);
         }
 
         // Make sure the renderList / particleSystemList are set when FrameGraphGeometryRendererTask.isReady() is called!
@@ -316,10 +316,10 @@ export class FrameGraphGeometryRendererTask extends FrameGraphTask {
 
         this._registerForRenderPassId(this._renderer.renderPassId);
 
-        const outputTextureDescription = this._frameGraph.textureManager.getTextureDescription(outputTextureHandle[0]);
+        const outputTextureDescription = outputTextureHandle.length > 0 ? this._frameGraph.textureManager.getTextureDescription(outputTextureHandle[0]) : null;
 
-        this._textureWidth = outputTextureDescription.size.width;
-        this._textureHeight = outputTextureDescription.size.height;
+        this._textureWidth = outputTextureDescription?.size.width ?? 0;
+        this._textureHeight = outputTextureDescription?.size.height ?? 0;
 
         // Create pass
         MaterialHelperGeometryRendering.MarkAsDirty(this._renderer.renderPassId, this.objectList.meshes || this._scene.meshes);
@@ -457,7 +457,7 @@ export class FrameGraphGeometryRendererTask extends FrameGraphTask {
             }
 
             const depthTextureDescription = this._frameGraph.textureManager.getTextureDescription(this.depthTexture);
-            if (depthTextureDescription.options.samples !== this.samples) {
+            if (depthTextureDescription.options.samples !== this.samples && this.textureDescriptions.length > 0) {
                 throw new Error(`FrameGraphGeometryRendererTask ${this.name}: the depth texture and the output texture must have the same number of samples`);
             }