feat(core): Support clear color, depth, and stencil on multiple views (#9650)

Author: chrisgervang

docs/api-reference/core/view.md

@@ -81,18 +81,37 @@ The `viewState` property is intended to support a number of use cases:
 * Overriding a partial set of view state properties from a selected view state.
 
 
-#### `clear` (boolean | object, optional) {#clear}
+#### `clear` (boolean, optional) {#clear}
 
-Clears the contents (pixels) of the viewport. The value of the `clear` prop is passed as an argument to luma.gl's `clear` function. If `true` clears color and depth buffers. If an object, behaviour is controlled by the following fields:
+Clears the contents (pixels) of the viewport. If `true` clears color, depth, and stencil buffers. Behavior is controlled with the `clearColor`, `clearDepth`, and `clearStencil` properties.
 
-* `color` (boolean or Array) - if not `false`, clears all active color buffers with either the provided color or the currently set clear color.
-* `depth` (boolean)  - if `true`, clears the depth buffer.
-* `stencil` (boolean) - if `true` clears the stencil buffer.
-
-Note that deck.gl always clears the screen before each render, and clearing, while cheap, is not totally free. This means that viewports should only specify the `clear` property if they need additional clearing, e.g. because they are rendering on top of another viewport, or want to have a different background color etc.
+Note that deck.gl always clears the screen before each render, and clearing, while cheap, is not totally free. This means that viewports should only clear the viewport if they need additional clearing, e.g. because they are rendering on top of another viewport, or want to have a different background color etc.
 
 Default `false`.
 
+#### `clearColor` (number[] | false, optional) {#clearcolor}
+
+Specifies the color to clear the viewport with, as an array of four numbers `[r, g, b, a?]`. Each channel should be an integer between 0 and 255. For example, `[255, 0, 0, 255]` for opaque red. If `clearColor` is `false`, the depth buffer will not be cleared. If `clear` is set to `false`, this property will be ignored.
+
+Default `[0, 0, 0, 0]` (transparent).
+
+#### `clearDepth` (number | false, optional) {#cleardepth}
+
+Specifies the depth buffer value to clear the viewport with, as number between `0.0` and `1.0`. If `clearDepth` is `false`, the depth buffer will not be cleared. If `clear` is set to `false`, this property will be ignored.
+
+Default `1.0` (far plane).
+
+#### `clearStencil` (number | false, optional) {#clearstencil}
+
+Specifies the stencil buffer value to clear the viewport with, as number between `0` and `255`. If `clearStencil` is `false`, the depth buffer will not be cleared. If `clear` is set to `false`, this property will be ignored.
+
+Default `0` (clear).
+
+**Examples:**
+
+*   Clearing to a solid color: `new View({clear: true, clearColor: [80, 120, 200, 255]})`
+*   Clearing color and stencil but not depth: `new View({clear: true, clearColor: [50, 50, 50, 255], clearDepth: false})`
+*   No clearing at all: `new View({})` or `new View({clear: false})`
 
 
 ## Methods

modules/core/src/passes/layers-pass.ts

@@ -4,6 +4,7 @@
 
 import type {Device, Parameters, RenderPassParameters} from '@luma.gl/core';
 import type {Framebuffer, RenderPass} from '@luma.gl/core';
+import type {NumberArray4} from '@math.gl/core';
 
 import Pass from './pass';
 import type Viewport from '../viewports/viewport';
@@ -80,13 +81,13 @@ export default class LayersPass extends Pass {
       parameters.colorMask = colorMask;
     }
     if (options.scissorRect) {
-      parameters.scissorRect = options.scissorRect as [number, number, number, number];
+      parameters.scissorRect = options.scissorRect as NumberArray4;
     }
 
     const renderPass = this.device.beginRenderPass({
       framebuffer: options.target,
       parameters,
-      clearColor: clearColor as [number, number, number, number],
+      clearColor: clearColor as NumberArray4,
       clearDepth,
       clearStencil
     });
@@ -217,7 +218,21 @@ export default class LayersPass extends Pass {
   /* eslint-disable max-depth, max-statements, complexity */
   private _drawLayersInViewport(
     renderPass: RenderPass,
-    {layers, shaderModuleProps: globalModuleParameters, pass, target, viewport, view},
+    {
+      layers,
+      shaderModuleProps: globalModuleParameters,
+      pass,
+      target,
+      viewport,
+      view
+    }: {
+      layers: Layer[];
+      shaderModuleProps: Record<string, any>;
+      pass: string;
+      target?: Framebuffer | null;
+      viewport: Viewport;
+      view?: View;
+    },
     drawLayerParams: DrawLayerParameters[]
   ): RenderStats {
     const glViewport = getGLViewport(this.device, {
@@ -226,18 +241,42 @@ export default class LayersPass extends Pass {
       viewport
     });
 
-    if (view && view.props.clear) {
-      const clearOpts = view.props.clear === true ? {color: true, depth: true} : view.props.clear;
-      const clearRenderPass = this.device.beginRenderPass({
-        framebuffer: target,
-        parameters: {
-          viewport: glViewport,
-          scissorRect: glViewport
-        },
-        clearColor: clearOpts.color ? [0, 0, 0, 0] : false,
-        clearDepth: clearOpts.depth ? 1 : false
-      });
-      clearRenderPass.end();
+    if (view) {
+      const {clear, clearColor, clearDepth, clearStencil} = view.props;
+      if (clear) {
+        // If clear option is set, clear all buffers by default.
+        let colorToUse: NumberArray4 | false = [0, 0, 0, 0];
+        let depthToUse: number | false = 1.0;
+        let stencilToUse: number | false = 0;
+
+        if (Array.isArray(clearColor)) {
+          colorToUse = [...clearColor.slice(0, 3), clearColor[3] || 255].map(
+            c => c / 255
+          ) as NumberArray4;
+        } else if (clearColor === false) {
+          colorToUse = false;
+        }
+
+        if (clearDepth !== undefined) {
+          depthToUse = clearDepth;
+        }
+
+        if (clearStencil !== undefined) {
+          stencilToUse = clearStencil;
+        }
+
+        const clearRenderPass = this.device.beginRenderPass({
+          framebuffer: target,
+          parameters: {
+            viewport: glViewport,
+            scissorRect: glViewport
+          },
+          clearColor: colorToUse,
+          clearDepth: depthToUse,
+          clearStencil: stencilToUse
+        });
+        clearRenderPass.end();
+      }
     }
 
     // render layers in normal colors
@@ -252,7 +291,7 @@ export default class LayersPass extends Pass {
 
     // render layers in normal colors
     for (let layerIndex = 0; layerIndex < layers.length; layerIndex++) {
-      const layer = layers[layerIndex] as Layer;
+      const layer = layers[layerIndex];
       const drawLayerParameters = drawLayerParams[layerIndex];
       const {shouldDrawLayer} = drawLayerParameters;
 
@@ -454,7 +493,7 @@ function getGLViewport(
     viewport
   }: {
     shaderModuleProps: any;
-    target?: Framebuffer;
+    target?: Framebuffer | null;
     viewport: Viewport;
   }
 ): [number, number, number, number] {

modules/core/src/views/view.ts

@@ -31,8 +31,14 @@ export type CommonViewProps<ViewState> = {
     top?: number | string;
     bottom?: number | string;
   } | null;
-  /** When using multiple views, set this flag to wipe the pixels drawn by other overlaping views */
+  /** When using multiple views, set this flag to wipe the pixels drawn by other overlapping views. Default `false` */
   clear?: boolean;
+  /** Color to clear the viewport with, in RGBA format [r, g, b, a?]. Values are 0-255. Default `[0, 0, 0, 0]` (transparent). */
+  clearColor?: number[] | false;
+  /** Depth buffer value to clear the viewport with, between 0.0 - 1.0. Default `1.0` (far plane). */
+  clearDepth?: number | false;
+  /** Stencil buffer Value to clear the viewport with, between 0 - 255. Default `0` (clear). */
+  clearStencil?: number | false;
   /** State of the view */
   viewState?:
     | string

test/render/golden-images/multi-view.png

@@ -133,5 +133,54 @@ export default [
       ],
       goldenImage: `./test/render/golden-images/globe-mvt.png`
     };
-  })
+  }),
+  {
+    name: 'multi-view',
+    views: [
+      new MapView({id: 'background', clear: true, clearColor: [0, 0, 255, 128]}),
+      new MapView({
+        id: 'transparent',
+        x: 0,
+        y: 0,
+        width: '50%',
+        height: '50%',
+        clear: true
+      }),
+      new MapView({
+        id: 'green',
+        x: '50%',
+        y: 0,
+        width: '50%',
+        height: '50%',
+        clear: true,
+        clearColor: [0, 255, 0]
+      }),
+      new MapView({
+        id: 'clearing-color-disabled',
+        x: 0,
+        y: '50%',
+        width: '50%',
+        height: '50%',
+        clear: true,
+        clearColor: false
+      }),
+      new MapView({id: 'default', x: '50%', y: '50%', width: '50%', height: '50%'})
+    ],
+    viewState: {
+      latitude: 0,
+      longitude: 0,
+      zoom: 0,
+      pitch: 0,
+      bearing: 0
+    },
+    layers: [
+      new ScatterplotLayer({
+        data: getRes0Cells(),
+        getPosition: d => cellToLatLng(d).reverse(),
+        radiusMinPixels: 4,
+        getFillColor: [0, 0, 0]
+      })
+    ],
+    goldenImage: './test/render/golden-images/multi-view.png'
+  }
 ];