externalRenderers

AMD: require(["esri/views/3d/externalRenderers"], (externalRenderers) => { /* code goes here */ });
ESM: import * as externalRenderers from "@arcgis/core/views/3d/externalRenderers.js";
Object: esri/views/3d/externalRenderers
Since: ArcGIS Maps SDK for JavaScript 4.0
Deprecated since 4.29. Use the new RenderNode instead.

SceneView uses WebGL version 2.0 to render the map/scene on screen. The ArcGIS Maps SDK for JavaScript offers a low-level interface to access the SceneView's WebGL context, and thus enables creating custom visualizations that interact with the scene the same way as built-in layers. Developers can either write WebGL code directly, or integrate with third-party WebGL libraries.

Porting to custom render nodes

A RenderNode provides an extended functionality over the deprecated externalRenderers API. It can consume additional input framebuffers and can replace the current framebuffer with a new, modified version. The following section provides a guideline on how to port an external renderer implementation to a RenderNode implementation.

The RenderNode is meant to be used as base class instead of providing an interface by global function pointers. The subclass derived from the RenderNode has to provide details about when the render function should be called. For external renderer the output is either "opaque-color" or "transparent-color". The required inputs will be "opaque-color" or "transparent-color" as well. The RenderNode does allow additional inputs. Check out the doc for RenderNodeInput and RenderNodeOutput for details. Once a RenderNode is constructed it is added automatically to the provided view.

 require(["esri/Map", "esri/views/SceneView", "esri/views/3d/webgl/RenderNode"], function (
  Map,
  SceneView,
  RenderNode
) {
  export const ExternalRenderNode = RenderNode.createSubclass({
    constructor() {
      this.consumes = { required: ["opaque-color"] };
      this.produces = "opaque-color";
    },

The RenderNode needs to define a render function, similar to the external renderer interface. The render function allows explicit handling of render targets and is required to return an output framebuffer. Inputs can either be used as textures, or can be bound directly to render top of the existing framebuffer. The deprecated externalRenderers API always updated the bound framebuffer. Using bindRenderTarget will allow you to keep the existing rendering function:

  export const ExternalRenderNode = RenderNode.createSubclass({
   ...
    render(inputs) {
      this.resetWebGLState();
      const output = this.bindRenderTarget();

      ...existing render function code...
      return output;
    }
  });
}

The setup and dispose functions do not exist in the render node API. Instead, a custom render node implementation can watch the view.ready property:

  export const ExternalRenderNode = RenderNode.createSubclass({
   ...
   initialize(): void {
     this.addHandles(
       watch(
         () => this.view.ready,
         (ready) => {
           if (ready) {
             setup();
           } else {
             dispose();
           }
         },
         initial,
       ),
     );
   }
 }

The RenderContext passed to the render function is deprecated. All its properties are available on the RenderNode instance with the same name. The now deprecated function externalRenderers.requestRender(view) is also available on the RenderNode instance.

Method Overview

Name Return Type Summary Object
externalRenderers
externalRenderers
RenderCameraexternalRenderers
externalRenderers
externalRenderers
externalRenderers
externalRenderers

Method Details

add

Method
add(view, renderer)static
Deprecated since 4.29. Use new RenderNode instead.
Parameters
view SceneView

The view to which to attach the external renderer.

renderer ExternalRenderer

The external renderer.

fromRenderCoordinates

Method
fromRenderCoordinates()static
Deprecated since 4.29. Use webgl instead.

getRenderCamera

Method
getRenderCamera(){RenderCamera}static
Deprecated since 4.29. Use new RenderNode.camera instead.
Returns
Type Description
RenderCamera Returns a render camera instance.

remove

Method
remove(view, renderer)static
Deprecated since 4.29. Use new RenderNode instead.
Parameters
view SceneView

The view from which to remove the external renderer.

renderer ExternalRenderer

The external renderer.

renderCoordinateTransformAt

Method
renderCoordinateTransformAt()static
Deprecated since 4.29. Use webgl instead.

requestRender

Method
requestRender()static
Deprecated since 4.29. Use new RenderNode.requestRender() instead.

toRenderCoordinates

Method
toRenderCoordinates()static
Deprecated since 4.29. Use webgl instead.

Type Definitions

ExternalRenderer

Type Definition
ExternalRenderer Object
Deprecated since 4.29. Use new RenderNode instead.

Defines an external renderer using callbacks and properties.

Properties
optional

Typically called once after adding the external renderer to a view, or whenever the SceneView becomes ready. It may be called again if the ready state cycles, for example when a different Map is assigned to the view. Receives a single parameter of type RenderContext.

optional

Called in every frame to execute the state update and draw calls. Receives a single parameter of type RenderContext.

optional

Called when the external renderer is removed from a view, or when the ready state of the view turns false. Receives a single parameter of type RenderContext.

RenderContext

Type Definition
RenderContext Object
Deprecated since 4.29. Use new RenderNode instead.

The object passed as a parameter to every call to setup and render the external renderer.

Properties

The WebGL rendering context.

camera RenderCamera

The camera used to render the current frame.

sunLight SunLight

The lighting used by SceneView to render the current frame.

resetWebGLState Function

A convenience function provided to completely reset the WebGL state after using it.

bindRenderTarget Function

Binds the color and depth buffers an external renderer is supposed to render into.

RenderContextCallback

Type Definition
RenderContextCallback(context)
Deprecated since 4.29. Use new RenderNode.render instead.

Callback to be called with a render context (used in the setup and render phases of the external renderer).

Parameter
context RenderContext
optional

The render context.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.