externalRenderers

SceneView uses WebGL to render the map/scene on screen. The ArcGIS API 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.

Important notes

This interface is experimental. Please read the following information carefully before using it in a product:

It is not possible to shield users of this interface from SceneView internal implementation details. Therefore, this interface should be considered not stable and subject to changes in upcoming minor releases of the ArcGIS API for JavaScript.

Because of the complex nature of WebGL and hardware-accelerated 3D rendering, this interface should only be used by expert developers that are experienced with WebGL or OpenGL.

Improper use of WebGL might not only break the custom rendering, but also the rendering of SceneView itself.

Esri does not provide any support for issues related to WebGL rendering in custom rendering code, or for issues that arise in SceneView rendering while using custom rendering code.

Integration with third-party libraries is only possible under certain conditions. Specifically, the third-party library has to be capable of working on the same WebGL context as SceneView, and able to set the relevant parts of the WebGL state in every frame.

We discourage using multiple custom renderers simultaneously, especially when developed by multiple parties.

The second parameter to externalRenderers.add() is an object which has to contain at least the two methods setup and render:

var myExternalRenderer = {
setup: function(context) {
// Executed once after the external renderer is added to a view. You can use this function to allocate all static// WebGL resources (shaders, buffers, etc.)
},
render: function(context) {
// Executed in every frame to draw geometry to the canvas. Tasks done in this function:// * Update the state of dynamic resources// * Set the WebGL state as needed for rendering// * Issue WebGL draw calls
}
}

The context variable passed to all methods of the external renderer object contains a reference to the WebGLcontext, and other information needed for rendering: RenderContext. You can execute WebGL commands directly on the WebGL context:

Requesting redraws

SceneView only renders a frame when there have been changes to the view, for example when the camera has moved or new data is available for display. Frames are always redrawn from the ground up, which means that external renderers will get called in each frame that is drawn.

Managing WebGL state

The ArcGIS API for JavaScript offers a guarantee at the time of the call to setup and render that all WebGL state variables are set to their respective defaults according to the WebGL specification. The only exception to this is gl.FRAMEBUFFER_BINDING which is set to the internally used framebuffer. For more details see the section on binding the correct render target. In return, it is required that users of the interface revert the WebGL context to the same state before returning control to the API. Failure to do so might lead to undefined behavior. For convenience, a function resetWebGLState() is offered on the context parameter passed to setup and render. This function can be called to completely reset all WebGL state. Because this function conservatively sets all WebGL state, it might incur a performance overhead; therefore, we suggest users instead keep track of the specific WebGL state that is modified, and reset that part of the state manually.

Binding the correct render target

Internally, the SceneView renders into an intermediate render target, instead of the default framebuffer provided by the WebGL context. This render target is already bound when setup and render are called and draw calls will be made to the correct buffer. Should you however bind another framebuffer with a call to gl.bindFramebuffer(), be aware that subsequent calls to gl.bindFramebuffer(null) will not bind the correct render target expected by the ArcGIS API for JavaScript. Consequently, WebGL draw calls issued afterwards would not show up on screen. Instead, a function bindRenderTarget() is offered on the RenderContext parameter passed to setup and render which will bind the correct color and depth buffers.

Coordinate systems

When working with the external renderer interface and especially in the context of WebGL, coordinates have to be specified in the internal rendering coordinate system of SceneView. This coordinate system depends on the viewingMode of the view:

In local viewing mode, it is equal to the coordinate system defined by the spatial reference of the view.

In global viewing mode, it is an ECEF coordinate system where the X-axis points to 0°N 0°E, the Y-axis points to 0°N 90°E, and the Z-axis points to the North Pole. The virtual globe is drawn as a perfect sphere with a radius of 6378137, so the unit of the coordinate system should be considered meters.

Precision issues

In global scenes, the precision of 32-bit floating point arithmetic is not sufficient for visualizations that go beyond global scale (i.e. country scale to city scale). When zooming the view beyond a certain scale, geometries will appear to wobble or jitter, and generally appear displaced. The same applies to local scenes where geometries are far away from the origin of the coordinate system.

In general, you should ensure that all arithmetic done in JavaScript is done in double precision. This is the case for normal JavaScript arithmetic, but you should specifically avoid using Float32Array unless you can rule out precision issues.

However, WebGL does not support 64 bit floating point arithmetic. A simple way to work around this limitation is to render scenes with a local origin:

Pick a local origin position, approximately at the center of your data.

Subtract the local origin position from all positional data (vertex data, uniforms, etc.) before passing it into WebGL.

Also subtract the local origin from the translational part of the view transformation matrix.

This technique will cause the data to be rendered in a local coordinate frame, and thus avoid the large numbers which would otherwise be needed to place the data at the right location. Multiple local origins are needed if the data covers large extents with high detail. Note that the local origin has to be representable exactly in 32 bit floating point, which is best achieved by storing the local origin itself as a Float32Array.

A linear array of one or more vectors that are interpreted as XYZ coordinates. For example, two position vectors would be represented as [x1, y1, z1, x2, y2, z2]. This must contain at least srcStart + 3 * count elements.

Computes a 4x4 affine transformation matrix that constitutes a linear coordinate transformation from a local Cartesian coordinate system to the virtual world coordinate system. For example, this matrix can be used to transform the vertices of a 3D model to the rendering coordinate system.

The local Cartesian system is defined by its origin and the following axis definition:

X: Easting

Y: Northing

Z: Elevation

When view.viewingMode is global, a linear transformation does not take the curvature of the globe or other non-linear projection aspects into account. Thus, the resulting coordinates will only appear correct within a small region around the origin of the local Cartesian system.

A reference to an array where the 16 matrix elements will be stored. The resulting matrix follows OpenGL conventions where the translation components occupy the 13th, 14th and 15th elements. If undefined, a newly created matrix returned.

A linear array of one or more vectors which are interpreted as XYZ coordinates. For example, two position vectors would be represented as [x1, y1, z1, x2, y2, z2]. This must contain at least srcStart + 3 * count elements.

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.

The camera object passed to renderer callbacks in RenderContext. This is not the same as Camera. All properties are read-only and defined in terms of the internal rendering coordinate system (see the section on coordinate systems at the top of this page).

Vectors (Vec3) are presented as arrays with 3 elements (x, y, z). Matrices (Mat4) are presented as linear arrays with 16 elements following the OpenGL conventions where the translation components occupy the 13th, 14th, and 15th elements.

Properties:

viewMatrixMat4

A 4x4 matrix that transforms coordinates from world space to camera space.

viewInverseTransposeMatrixMat4

The inverse transpose of viewMatrix, used to transform normals from world space to camera space.

projectionMatrixMat4

A 4x4 matrix that defines the perspective projection transformation.

eyeVec3

The position of the camera in the internal Cartesian rendering coordinate system.

centerVec3

The camera target ("look at") position in the internal Cartesian rendering coordinate system.

Describes the lighting used by SceneView, derived from its sun lighting model. It consists of a directional Lambertian (diffuse) and a constant (ambient) term, which should be treated in the sense of the Phong Reflection Model.