Custom render passes on a camera

src/platform/graphics/render-pass.js

@@ -91,7 +91,20 @@ class DepthStencilAttachmentOps {
  */
 class RenderPass {
     /** @type {string} */
-    name;
+    name = '';
+
+    /**
+     * True if the render pass is enabled.
+     *
+     * @type {boolean}
+     */
+    enabled = true;
+
+    /**
+     * True if the render pass is enabled and execute function will be called. Note that before and
+     * after functions are called regardless of this flag.
+     */
+    executeEnabled = true;
 
     /**
      * The render target for this render pass:
@@ -147,48 +160,29 @@ class RenderPass {
     fullSizeClearRect = true;
 
     /**
-     * Custom function that is called to render the pass.
-     *
-     * @type {Function|undefined}
-     */
-    _execute;
-
-    /**
-     * True if the render pass is enabled and execute function will be called. Note that before and
-     * after functions are called regardless of this flag.
-     */
-    executeEnabled = true;
-
-    /**
-     * Custom function that is called before the pass has started.
+     * Render passes which need to be executed before this pass.
      *
-     * @type {Function|undefined}
+     * @type {RenderPass[]}
      */
-    _before;
+    beforePasses = [];
 
     /**
-     * Custom function that is called after the pass has fnished.
+     * Render passes which need to be executed after this pass.
      *
-     * @type {Function|undefined}
+     * @type {RenderPass[]}
      */
-    _after;
+    afterPasses = [];
 
     /**
      * Creates an instance of the RenderPass.
      *
      * @param {import('../graphics/graphics-device.js').GraphicsDevice} graphicsDevice - The
      * graphics device.
-     * @param {Function} [execute] - Custom function that is called to render the pass.
      */
-    constructor(graphicsDevice, execute) {
+    constructor(graphicsDevice) {
         DebugHelper.setName(this, this.constructor.name);
         Debug.assert(graphicsDevice);
         this.device = graphicsDevice;
-
-        this._execute = execute;
-    }
-
-    destroy() {
     }
 
     /**
@@ -227,15 +221,12 @@ class RenderPass {
     }
 
     before() {
-        this._before?.();
     }
 
     execute() {
-        this._execute?.();
     }
 
     after() {
-        this._after?.();
     }
 
     /**
@@ -280,34 +271,37 @@ class RenderPass {
      */
     render() {
 
-        const device = this.device;
-        const realPass = this.renderTarget !== undefined;
-        DebugGraphics.pushGpuMarker(device, `Pass:${this.name}`);
+        if (this.enabled) {
 
-        Debug.call(() => {
-            this.log(device, device.renderPassIndex);
-        });
+            const device = this.device;
+            const realPass = this.renderTarget !== undefined;
+            DebugGraphics.pushGpuMarker(device, `Pass:${this.name}`);
 
-        this.before();
+            Debug.call(() => {
+                this.log(device, device.renderPassIndex);
+            });
 
-        if (this.executeEnabled) {
-            if (realPass) {
-                device.startPass(this);
-            }
+            this.before();
 
-            this.execute();
+            if (this.executeEnabled) {
 
-            if (realPass) {
-                device.endPass(this);
-            }
-        }
+                if (realPass) {
+                    device.startPass(this);
+                }
 
-        this.after();
+                this.execute();
 
-        device.renderPassIndex++;
+                if (realPass) {
+                    device.endPass(this);
+                }
+            }
 
-        DebugGraphics.popGpuMarker(device);
+            this.after();
 
+            device.renderPassIndex++;
+
+            DebugGraphics.popGpuMarker(device);
+        }
     }
 
     // #if _DEBUG

src/scene/camera.js

@@ -42,6 +42,14 @@ class Camera {
      */
     renderPassDepthGrab = null;
 
+    /**
+     * Render passes used to render this camera. If empty, the camera will render using the default
+     * render passes.
+     *
+     * @type {import('../platform/graphics/render-pass.js').RenderPass[]}
+     */
+    renderPasses = [];
+
     constructor() {
         this._aspectRatio = 16 / 9;
         this._aspectRatioMode = ASPECT_AUTO;
@@ -101,6 +109,11 @@ class Camera {
 
         this.renderPassDepthGrab?.destroy();
         this.renderPassDepthGrab = null;
+
+        this.renderPasses.forEach((pass) => {
+            pass.destroy();
+        });
+        this.renderPasses.length = 0;
     }
 
     /**

src/scene/composition/layer-composition.js

@@ -120,9 +120,12 @@ class LayerComposition extends EventHandler {
     }
 
     destroy() {
-        // render actions
+        this.destroyRenderActions();
+    }
+
+    destroyRenderActions() {
         this._renderActions.forEach(ra => ra.destroy());
-        this._renderActions = null;
+        this._renderActions.length = 0;
     }
 
     _update() {
@@ -174,10 +177,19 @@ class LayerComposition extends EventHandler {
 
             // render in order of cameras sorted by priority
             let renderActionCount = 0;
+            this.destroyRenderActions();
+
             for (let i = 0; i < this.cameras.length; i++) {
                 const camera = this.cameras[i];
                 cameraLayers.length = 0;
 
+                // if the camera uses custom render passes, only add a dummy render action to mark
+                // the place where to add them during building of the frame graph
+                if (camera.camera.renderPasses.length > 0) {
+                    this.addDummyRenderAction(renderActionCount, camera);
+                    continue;
+                }
+
                 // first render action for this camera
                 let cameraFirstRenderAction = true;
                 const cameraFirstRenderActionIndex = renderActionCount;
@@ -218,7 +230,7 @@ class LayerComposition extends EventHandler {
 
                                 // add render action to describe rendering step
                                 const isTransparent = this.subLayerList[j];
-                                lastRenderAction = this.addRenderAction(this._renderActions, renderActionCount, layer, isTransparent, camera,
+                                lastRenderAction = this.addRenderAction(renderActionCount, layer, isTransparent, camera,
                                                                         cameraFirstRenderAction, postProcessMarked);
                                 renderActionCount++;
                                 cameraFirstRenderAction = false;
@@ -246,25 +258,25 @@ class LayerComposition extends EventHandler {
                 }
             }
 
-            // destroy unused render actions
-            for (let i = renderActionCount; i < this._renderActions.length; i++) {
-                this._renderActions[i].destroy();
-            }
-            this._renderActions.length = renderActionCount;
-
             this._logRenderActions();
         }
     }
 
-    // function adds new render action to a list, while trying to limit allocation and reuse already allocated objects
-    addRenderAction(renderActions, renderActionIndex, layer, isTransparent, camera, cameraFirstRenderAction, postProcessMarked) {
+    getNextRenderAction(renderActionIndex) {
+        Debug.assert(this._renderActions.length === renderActionIndex);
+        const renderAction = new RenderAction();
+        this._renderActions.push(renderAction);
+        return renderAction;
+    }
 
-        // try and reuse object, otherwise allocate new
-        /** @type {RenderAction} */
-        let renderAction = renderActions[renderActionIndex];
-        if (!renderAction) {
-            renderAction = renderActions[renderActionIndex] = new RenderAction();
-        }
+    addDummyRenderAction(renderActionIndex, camera) {
+        const renderAction = this.getNextRenderAction(renderActionIndex);
+        renderAction.camera = camera;
+        renderAction.useCameraPasses = true;
+    }
+
+    // function adds new render action to a list, while trying to limit allocation and reuse already allocated objects
+    addRenderAction(renderActionIndex, layer, isTransparent, camera, cameraFirstRenderAction, postProcessMarked) {
 
         // render target from the camera takes precedence over the render target from the layer
         let rt = layer.renderTarget;
@@ -276,43 +288,37 @@ class LayerComposition extends EventHandler {
 
         // was camera and render target combo used already
         let used = false;
+        const renderActions = this._renderActions;
         for (let i = renderActionIndex - 1; i >= 0; i--) {
             if (renderActions[i].camera === camera && renderActions[i].renderTarget === rt) {
                 used = true;
                 break;
             }
         }
 
-        // clear flags - use camera clear flags in the first render action for each camera,
-        // or when render target (from layer) was not yet cleared by this camera
-        const needsClear = cameraFirstRenderAction || !used;
-        let clearColor = needsClear ? camera.clearColorBuffer : false;
-        let clearDepth = needsClear ? camera.clearDepthBuffer : false;
-        let clearStencil = needsClear ? camera.clearStencilBuffer : false;
-
-        // clear buffers if requested by the layer
-        clearColor ||= layer.clearColorBuffer;
-        clearDepth ||= layer.clearDepthBuffer;
-        clearStencil ||= layer.clearStencilBuffer;
-
         // for cameras with post processing enabled, on layers after post processing has been applied already (so UI and similar),
         // don't render them to render target anymore
         if (postProcessMarked && camera.postEffectsEnabled) {
             rt = null;
         }
 
-        // store the properties - write all as we reuse previously allocated class instances
+        // store the properties
+        const renderAction = this.getNextRenderAction(renderActionIndex);
         renderAction.triggerPostprocess = false;
         renderAction.layer = layer;
         renderAction.transparent = isTransparent;
         renderAction.camera = camera;
         renderAction.renderTarget = rt;
-        renderAction.clearColor = clearColor;
-        renderAction.clearDepth = clearDepth;
-        renderAction.clearStencil = clearStencil;
         renderAction.firstCameraUse = cameraFirstRenderAction;
         renderAction.lastCameraUse = false;
 
+        // clear flags - use camera clear flags in the first render action for each camera,
+        // or when render target (from layer) was not yet cleared by this camera
+        const needsClear = cameraFirstRenderAction || !used;
+        if (needsClear) {
+            renderAction.setupClears(needsClear ? camera : undefined, layer);
+        }
+
         return renderAction;
     }
 
@@ -336,6 +342,11 @@ class LayerComposition extends EventHandler {
                 continue;
             }
 
+            // end of stacking if camera with custom render passes
+            if (ra.useCameraPasses) {
+                break;
+            }
+
             // camera stack ends when viewport or scissor of the camera changes
             const thisCamera = ra?.camera.camera;
             if (thisCamera) {
@@ -357,22 +368,27 @@ class LayerComposition extends EventHandler {
             Debug.trace(TRACEID_RENDER_ACTION, 'Render Actions for composition: ' + this.name);
             for (let i = 0; i < this._renderActions.length; i++) {
                 const ra = this._renderActions[i];
-                const layer = ra.layer;
-                const enabled = layer.enabled && this.isEnabled(layer, ra.transparent);
                 const camera = ra.camera;
-                const clear = (ra.clearColor ? 'Color ' : '..... ') + (ra.clearDepth ? 'Depth ' : '..... ') + (ra.clearStencil ? 'Stencil' : '.......');
-
-                Debug.trace(TRACEID_RENDER_ACTION, i +
-                    (' Cam: ' + (camera ? camera.entity.name : '-')).padEnd(22, ' ') +
-                    (' Lay: ' + layer.name).padEnd(22, ' ') +
-                    (ra.transparent ? ' TRANSP' : ' OPAQUE') +
-                    (enabled ? ' ENABLED ' : ' DISABLED') +
-                    (' RT: ' + (ra.renderTarget ? ra.renderTarget.name : '-')).padEnd(30, ' ') +
-                    ' Clear: ' + clear +
-                    (ra.firstCameraUse ? ' CAM-FIRST' : '') +
-                    (ra.lastCameraUse ? ' CAM-LAST' : '') +
-                    (ra.triggerPostprocess ? ' POSTPROCESS' : '')
-                );
+                if (ra.useCameraPasses) {
+                    Debug.trace(TRACEID_RENDER_ACTION, i +
+                        ('CustomPasses Cam: ' + (camera ? camera.entity.name : '-')));
+                } else {
+                    const layer = ra.layer;
+                    const enabled = layer.enabled && this.isEnabled(layer, ra.transparent);
+                    const clear = (ra.clearColor ? 'Color ' : '..... ') + (ra.clearDepth ? 'Depth ' : '..... ') + (ra.clearStencil ? 'Stencil' : '.......');
+
+                    Debug.trace(TRACEID_RENDER_ACTION, i +
+                        (' Cam: ' + (camera ? camera.entity.name : '-')).padEnd(22, ' ') +
+                        (' Lay: ' + layer.name).padEnd(22, ' ') +
+                        (ra.transparent ? ' TRANSP' : ' OPAQUE') +
+                        (enabled ? ' ENABLED ' : ' DISABLED') +
+                        (' RT: ' + (ra.renderTarget ? ra.renderTarget.name : '-')).padEnd(30, ' ') +
+                        ' Clear: ' + clear +
+                        (ra.firstCameraUse ? ' CAM-FIRST' : '') +
+                        (ra.lastCameraUse ? ' CAM-LAST' : '') +
+                        (ra.triggerPostprocess ? ' POSTPROCESS' : '')
+                    );
+                }
             }
         }
         // #endif

src/scene/composition/render-action.js

@@ -48,6 +48,9 @@ class RenderAction {
         // an array of view bind groups (the number of these corresponds to the number of views when XR is used)
         /** @type {import('../../platform/graphics/bind-group.js').BindGroup[]} */
         this.viewBindGroups = [];
+
+        // true if the camera should render using render passes it specifies
+        this.useCameraPasses = false;
     }
 
     // releases GPU resources
@@ -59,6 +62,12 @@ class RenderAction {
         this.viewBindGroups.length = 0;
     }
 
+    setupClears(camera, layer) {
+        this.clearColor = camera?.clearColorBuffer || layer.clearColorBuffer;
+        this.clearDepth = camera?.clearDepthBuffer || layer.clearDepthBuffer;
+        this.clearStencil = camera?.clearStencilBuffer || layer.clearStencilBuffer;
+    }
+
     get hasDirectionalShadowLights() {
         return this.directionalLights.length > 0;
     }