fix(arcgis): update arcgis module to use RenderNode instead of externalRenderers (#10257)

* fix(arcgis): Replace externalRenderers wth RenderNode

* test(arcgis): ensure renderer does not fail

* docs(arcgis): Replace externalRenderers references with RenderNode

* fix(arcgis): update to work with luna v9.2.6

* docs(arcgis): updates related to luma 9.x.x

* (arcgis) Improve integration

* (arcgis) Inline RenderNode setup into constructor

* (docs) Remove unneeded and potentially outdated docs

* (arcgis) Fix high-tilt detachment

* (docs) Update references to RenderNode

* (test) Coverage for core changes

* (arcgis) remove unused fbo

* (arcgis) drop luma.gl patch for v9.3.3

* (chore) remove unhelpful entries

* (chore) remove normalization hack

* (test) restore accidentally removed tests

* (chore) update loaders in website dependencies

* (docs) update the upgrade guide to reflect changes

* (docs) include loadScriptOptions info to the upgrade guide

Author: toddrun

docs/api-reference/arcgis/deck-renderer.md

@@ -1,6 +1,6 @@
 # DeckRenderer
 
-This class is an experimental implementation of the ArcGIS [ExternalRenderer](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-3d-externalRenderers.html#ExternalRenderer) interface and can be added to 3D views of maps created with the ArcGIS
+This class is an experimental implementation of the ArcGIS [RenderNode](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-3d-webgl-RenderNode.html) interface and can be added to 3D views of maps created with the ArcGIS
 API for JavaScript.
 
 
@@ -11,7 +11,6 @@ import {DeckRenderer} from '@deck.gl/arcgis';
 import {ScatterplotLayer} from '@deck.gl/layers';
 import ArcGISMap from '@arcgis/core/Map';
 import SceneView from '@arcgis/core/views/SceneView';
-import * as externalRenderers from '@arcgis/core/views/3d/externalRenderers';
 
 const sceneView = new SceneView({
   container: 'viewDiv',
@@ -38,8 +37,6 @@ const renderer = new DeckRenderer(sceneView, {
     })
   ]
 });
-
-externalRenderers.add(sceneView, renderer);
 ```
 
 
@@ -49,7 +46,7 @@ externalRenderers.add(sceneView, renderer);
 new DeckRenderer(sceneView, props)
 ```
 
-- `sceneView` ([SceneView](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-SceneView.html)) - the view to use this renderer with. `viewingMode` must be set to `'local'`.
+- `sceneView` ([SceneView](https://developers.arcgis.com/javascript/latest/api-reference/esri-views-SceneView.html)) - the view to use this renderer with. `viewingMode` must be set to `'local'`. `DeckRenderer` manages its internal deck.gl view state from the live `SceneView` camera and self-registers as a RenderNode; do not add it to `map.layers`.
 - `props` (object) - forwarded to a `Deck` instance. The following [Deck](../core/deck.md) props are supported:
 
 - `layers`

docs/api-reference/arcgis/overview.md

@@ -8,7 +8,7 @@ that acts as an interface between deck.gl and ArcGIS.
 
 2D integration with `MapView` is supported by the [DeckLayer](./deck-layer.md) class.
 
-3D integration with `SceneView` is experimental: see the [DeckRenderer](./deck-renderer.md) class.
+3D integration with `SceneView` is experimental and currently targets `viewingMode: 'local'`: see the [DeckRenderer](./deck-renderer.md) class.
 
 ## Installation
 

docs/developer-guide/base-maps/using-with-arcgis.md

@@ -10,4 +10,4 @@ Starting with v8.1, deck.gl has support for ArcGIS with the [@deck.gl/arcgis](..
 
 2D integration with `MapView` is supported by the [DeckLayer](../../api-reference/arcgis/deck-layer.md) class, see [pure JS example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/pure-js/arcgis).
 
-3D integration with `SceneView` is experimental: see the [DeckRenderer](../../api-reference/arcgis/deck-renderer.md) class.
+3D integration with `SceneView` is experimental and currently targets `viewingMode: 'local'`; `DeckRenderer` attaches as a RenderNode rather than a map layer. See the [DeckRenderer](../../api-reference/arcgis/deck-renderer.md) class.

docs/upgrade-guide.md

@@ -51,6 +51,53 @@ new Deck({
 - The experimental `_renderLayersInGroups` prop has been removed from `MapboxOverlay`. In interleaved mode, layers are now always rendered in groups by `beforeId` or `slot`, enabling cross-layer extension handling (e.g. MaskExtension, CollisionFilterExtension) by default. If you were using `_renderLayersInGroups: true`, simply remove the prop.
 - Note: extensions that require shared rendering context (MaskExtension, CollisionFilterExtension) only work between layers in the same group. Ensure affected layers share the same `beforeId` or `slot` value.
 
+### @deck.gl/arcgis
+
+`DeckRenderer` now integrates with ArcGIS `SceneView` through `RenderNode` instead of `externalRenderers`.
+
+If your app uses 3D ArcGIS integration, migrate as follows:
+
+- Load `esri/views/3d/webgl/RenderNode` instead of `esri/views/3d/externalRenderers`.
+- If you pass a custom `esri` object to `loadArcGISModules`, make sure it exposes `esri.views['3d'].webgl.RenderNode`.
+- Remove `externalRenderers.add(sceneView, renderer)`. `DeckRenderer` now self-registers as a `RenderNode`.
+- `SceneView` integration still requires `viewingMode: 'local'`.
+- If you are loading ArcGIS via `esri-loader`, consider pinning the ArcGIS JS API script with `loadScriptOptions` (for example, `{url: 'https://js.arcgis.com/4.32/'}`) to avoid unintentional version drift.
+
+```js
+// Before
+loadArcGISModules([
+  'esri/Map',
+  'esri/views/SceneView',
+  'esri/views/3d/externalRenderers'
+]).then(({DeckRenderer, modules}) => {
+  const [ArcGISMap, SceneView, externalRenderers] = modules;
+  const sceneView = new SceneView({
+    map: new ArcGISMap({basemap: 'dark-gray-vector'}),
+    viewingMode: 'local'
+  });
+
+  const renderer = new DeckRenderer(sceneView, {layers});
+  externalRenderers.add(sceneView, renderer);
+});
+
+// After
+loadArcGISModules([
+  'esri/Map',
+  'esri/views/SceneView',
+  'esri/views/3d/webgl/RenderNode'
+], {
+  url: 'https://js.arcgis.com/4.32/'
+}).then(({DeckRenderer, modules}) => {
+  const [ArcGISMap, SceneView] = modules;
+  const sceneView = new SceneView({
+    map: new ArcGISMap({basemap: 'dark-gray-vector'}),
+    viewingMode: 'local'
+  });
+
+  new DeckRenderer(sceneView, {layers});
+});
+```
+
 ### Widgets
 
 The following widgets have breaking changes in v9.3:
@@ -63,7 +110,6 @@ The following widgets have breaking changes in v9.3:
 - [ThemeWidget](./api-reference/widgets/theme-widget.md) - no longer experimental (removed underscore in export)
 - [LoadingWidget](./api-reference/widgets/loading-widget.md) - no longer experimental (removed underscore in export)
 
-
 ## Upgrading to v9.1
 
 ### User input handling

modules/arcgis/src/commons.ts

@@ -19,7 +19,6 @@ export type RenderResources = {
   texture: Texture;
   model: Model;
   fbo: Framebuffer;
-  _externalFramebuffer?: {handle: WebGLFramebuffer; wrapper: Framebuffer};
 };
 
 async function createDeckInstance(gl: WebGL2RenderingContext): Promise<{
@@ -87,16 +86,18 @@ out vec4 fragColor;
 
 void main(void) {
     vec4 imageColor = texture(deckglTexture, v_texcoord);
-    imageColor.rgb *= imageColor.a;
+    // FBO stores premultiplied RGBA (rgb already multiplied by alpha).
+    // The composite blend (ONE, ONE_MINUS_SRC_ALPHA) handles premultiplied
+    // input correctly; multiplying again here would darken overlays.
     fragColor = imageColor;
 }
     `,
     bindings: {
       deckglTexture: texture
     },
     parameters: {
-      depthWriteEnabled: true,
-      depthCompare: 'less-equal',
+      depthWriteEnabled: false,
+      depthCompare: 'always',
       blendColorSrcFactor: 'one',
       blendColorDstFactor: 'one-minus-src-alpha',
       blendAlphaSrcFactor: 'one',
@@ -128,6 +129,18 @@ void main(void) {
 
     _customRender: redrawReason => {
       if (redrawReason === 'arcgis') {
+        // ArcGIS renders with alphaSrc=ZERO (preserves destination alpha for its
+        // own compositing pipeline). Without resetting this, deck layers inherit
+        // that blend state and write alpha=0 into the FBO, making the composite
+        // shader output (0,0,0,0) everywhere. Reset to standard premultiplied-alpha
+        // blend so the FBO stores correct RGBA for the composite pass.
+        const glCtx = (device as WebGLDevice).gl;
+        glCtx.blendFuncSeparate(
+          glCtx.ONE,
+          glCtx.ONE_MINUS_SRC_ALPHA,
+          glCtx.ONE,
+          glCtx.ONE_MINUS_SRC_ALPHA
+        );
         deckInstance._drawLayers(redrawReason);
       } else {
         this.redraw();
@@ -149,44 +162,81 @@ export function render(
     altitude?: number;
     pitch: number;
     bearing: number;
+    views?: unknown;
+    viewState?: unknown;
   }
 ) {
   const {model, deck, fbo} = resources;
   const device = model.device;
   if (device instanceof WebGLDevice) {
-    const {width, height, ...viewState} = viewport;
+    // @ts-ignore device.getParametersWebGL should return `any` not `void`?
+    const rawScreenFbo: WebGLFramebuffer | null = device.getParametersWebGL(GL.FRAMEBUFFER_BINDING);
+    const {width, height, views, viewState, ...defaultViewState} = viewport;
 
     /* global window */
     const dpr = window.devicePixelRatio;
     const pixelWidth = Math.round(width * dpr);
     const pixelHeight = Math.round(height * dpr);
 
-    // Wrap the external framebuffer handle so luma.gl treats it as a proper Framebuffer resource.
-    const externalFbo = device.getParametersWebGL(GL.FRAMEBUFFER_BINDING);
-    let screenFbo: Framebuffer | null = null;
-    if (externalFbo) {
-      if (resources._externalFramebuffer?.handle !== externalFbo) {
-        resources._externalFramebuffer?.wrapper.destroy();
-        const wrapper = device.createFramebuffer({
-          handle: externalFbo,
-          width: pixelWidth,
-          height: pixelHeight
-        });
-        resources._externalFramebuffer = {handle: externalFbo, wrapper};
-      }
-      screenFbo = resources._externalFramebuffer!.wrapper;
-    }
-
     fbo.resize({width: pixelWidth, height: pixelHeight});
 
-    deck.setProps({viewState});
+    // luma's Framebuffer.resize() clones and destroys the color attachment texture when
+    // dimensions change, leaving the cached texture reference and the model sampler binding
+    // pointing at a destroyed GPU handle. Re-sync if the attachment was replaced.
+    const currentTexture =
+      (fbo.colorAttachments[0] as any).texture ?? (fbo.colorAttachments[0] as unknown as Texture);
+    if (currentTexture !== resources.texture) {
+      resources.texture = currentTexture;
+      (model as any).setBindings({deckglTexture: currentTexture});
+    }
+
+    // Pass CSS pixel dimensions — deck handles DPR internally. Passing physical
+    // pixels would double-apply DPR and project layer geometry off-screen.
+    // Without width/height, deck's viewport aspect diverges from ArcGIS's,
+    // causing the overlay to drift off the ground plane under tilt/rotation.
+    const deckProps: any = {
+      width,
+      height,
+      viewState: viewState || defaultViewState
+    };
+    if (views) {
+      deckProps.views = views;
+    }
+    deck.setProps(deckProps);
     // redraw deck immediately into deckFbo
     deck.redraw('arcgis');
 
     // We overlay the texture on top of the map using the full-screen quad.
+    const {gl} = device;
+
+    // drawBuffers is per-FBO state not tracked by luma's state cache;
+    // restore it for the screen FBO after rendering to the offscreen FBO.
+    if (rawScreenFbo) {
+      gl.bindFramebuffer(GL.FRAMEBUFFER, rawScreenFbo);
+      gl.drawBuffers([GL.COLOR_ATTACHMENT0]);
+    } else {
+      gl.drawBuffers([GL.BACK]);
+    }
+
+    // The model sets blend factors but not blend:true, so
+    // setDeviceParameters won't enable blending on its own.
+    gl.enable(GL.BLEND);
+    gl.blendFuncSeparate(GL.ONE, GL.ONE_MINUS_SRC_ALPHA, GL.ONE, GL.ONE_MINUS_SRC_ALPHA);
+    gl.blendEquationSeparate(GL.FUNC_ADD, GL.FUNC_ADD);
+
+    // luma's WEBGLRenderPass duck-types the framebuffer prop, reading `.handle`, `.width`,
+    // `.height`, and `.colorAttachments`. A raw WebGLFramebuffer has none of those, which
+    // breaks viewport auto-setup and draw-buffer selection. Build a minimal adapter that
+    // luma's state tracker accepts; `'handle' in obj` is true, so the raw FBO is bound.
+    const screenFboAdapter = {
+      handle: rawScreenFbo,
+      width: pixelWidth,
+      height: pixelHeight,
+      colorAttachments: [null]
+    };
 
     const textureToScreenPass = device.beginRenderPass({
-      framebuffer: screenFbo,
+      framebuffer: screenFboAdapter as any,
       parameters: {viewport: [0, 0, pixelWidth, pixelHeight]},
       clearColor: false,
       clearDepth: false
@@ -204,5 +254,4 @@ export function finalizeResources(resources: RenderResources) {
   resources.model.destroy();
   resources.fbo.destroy();
   resources.texture.destroy();
-  resources._externalFramebuffer?.wrapper.destroy();
 }