• esri/views

BaseLayerViewGL2D

AMD: require(["esri/views/2d/layers/BaseLayerViewGL2D"], (BaseLayerViewGL2D) => { /* code goes here */ });
ESM: import BaseLayerViewGL2D from "@arcgis/core/views/2d/layers/BaseLayerViewGL2D";
Class: esri/views/2d/layers/BaseLayerViewGL2D
Inheritance: BaseLayerViewGL2D LayerView Accessor
Since: ArcGIS Maps SDK for JavaScript 4.11

Represents the LayerView of a Layer after it has been added to a Map with a MapView. In contrast to the related class BaseLayerView2D, this one exposes WebGL rendering capabilities.

Important notes

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

Due to the nature of WebGL it is not possible to fully sandbox user-supplied code, and its malfunctions can affect the performance, visual quality and even stability of the entire MapView. For this reason, Esri does not provide any support for issues related to WebGL rendering in custom rendering code, or for issues that arise in MapView rendering while using custom rendering code.

This class may be extended to create a custom LayerView for a Layer. A LayerView is created on demand by the MapView when a layer is added the to list of layers of its map.

The subclass can implement multiple functions of the LayerView lifecycle.

  • First, the attach() method is called when the LayerView is about to start drawing the layer's content; it is usually responsible for resource allocation.
  • Then during the life of the LayerView the render() method is called once per frame; it must complete drawing before returning.
  • Finally the detach() method is called after the layer is removed from the map; it releases all allocated resources and stops on-going requests.

Each of these functions has access to the MapView's WebGL context through the instance property this.context. The developer must provide own shaders, meshes and textures, and is responsible for setting the required GL states on the context.

As a convenience for the developer, starting with version 4.14 of the API, BaseLayerViewGL2D includes tessellation helper methods; the developer can supply Point, Multipoint, Polyline, Extent, or Polygon geometries and have them converted to abstract descriptions of triangle meshes that can be easily fed to the GPU as vertex and index buffers. The SDK sample explains in detail how to use the tessellation helpers and how to write compatible shaders.

See also
Example
let CustomLayerView2D = BaseLayerViewGL2D.createSubclass({
   render(renderParameters) {
     const gl = this.context;

     ...
   }

   attach() {
     const gl = this.context;

     ...
   }

   detach() {
     const gl = this.context;

     ...
   }
 });

 let CustomTileLayer = Layer.createSubclass({
   tileInfo: TileInfo.create({ spatialReference: { wkid: 3857 }}),

   createLayerView(view) {
     if (view.type === "2d") {
       return new CustomLayerView2D({
         view: view,
         layer: this
       });
     }
   }
 });

Constructors

new BaseLayerViewGL2D(properties)
Parameter
properties Object
optional

See the properties for a list of all the properties that may be passed into the constructor.

Property Overview

Any properties can be set, retrieved or listened to. See the Working with Properties topic.
Show inherited properties Hide inherited properties
Name Type Summary Class
WebGLRenderingContext|WebGL2RenderingContext

The WebGL rendering context associated to this layer view.

more details
BaseLayerViewGL2D
String

The name of the class.

more details
Accessor
Layer

References the layer this LayerView represents.

more details
BaseLayerViewGL2D
Boolean

Indicates if the spatialReference of the MapView is supported by the layer view.

more details
LayerView
Boolean

Value is true if the layer is suspended (i.e., layer will not redraw or update itself when the extent changes).

more details
LayerView
Tile[]

The array of BaseLayerViewGL2D objects computed to cover the MapView's visible area.

more details
BaseLayerViewGL2D
Boolean

Value is true when the layer is updating; for example, if it is in the process of fetching data.

more details
LayerView
MapView

References the MapView this LayerView belongs to.

more details
BaseLayerViewGL2D
Boolean

When true, the layer is visible in the view.

more details
LayerView

Property Details

The WebGL rendering context associated to this layer view.

declaredClass Stringreadonly inherited

The name of the class. The declared class name is formatted as esri.folder.className.

layer Layer

References the layer this LayerView represents.

spatialReferenceSupported Booleanreadonly inherited
Since: ArcGIS Maps SDK for JavaScript 4.23

Indicates if the spatialReference of the MapView is supported by the layer view. When false layer view will be suspended.

See also
suspended Booleanreadonly inherited

Value is true if the layer is suspended (i.e., layer will not redraw or update itself when the extent changes).

See also
tiles Tile[]

The array of BaseLayerViewGL2D objects computed to cover the MapView's visible area. This array is updated when the view is animating or the user is interacting with it. Then if tiles have been added or removed, tilesChanged() is called.

See also
updating Booleanreadonly inherited

Value is true when the layer is updating; for example, if it is in the process of fetching data.

Default Value:false
view MapView

References the MapView this LayerView belongs to.

visible Boolean inherited

When true, the layer is visible in the view. Value of this property is inherited from the layer.visible unless the developer overrides it. The layerView.visible will take precedence over layer.visible if both properties are set.

Default Value:true

Method Overview

Show inherited methods Hide inherited methods
Name Return Type Summary Class

Adds one or more handles which are to be tied to the lifecycle of the object.

more details
Accessor

Method called after the LayerView is created and right before it starts drawing the layer's content.

more details
BaseLayerViewGL2D

Bind the designated rendering output surface and restore the correct viewport.

more details
BaseLayerViewGL2D

Method called after the layer is removed and the LayerView is about to be removed.

more details
BaseLayerViewGL2D
RenderTarget

Get the designated rendering output surface and corresponding viewport configuration.

more details
BaseLayerViewGL2D
Boolean

Returns true if a named group of handles exist.

more details
Accessor
Promise<Graphic[]>

Method to implement that is responsible for providing objects hit at the specified screen coordinates.

more details
BaseLayerViewGL2D
Boolean

isFulfilled() may be used to verify if creating an instance of the class is fulfilled (either resolved or rejected).

more details
LayerView
Boolean

isRejected() may be used to verify if creating an instance of the class is rejected.

more details
LayerView
Boolean

isResolved() may be used to verify if creating an instance of the class is resolved.

more details
LayerView

Removes a group of handles owned by the object.

more details
Accessor

The method to implement that is responsible of drawing the content of the layer.

more details
BaseLayerViewGL2D

The LayerView can call this method to ask the MapView to schedule a new rendering frame.

more details
BaseLayerViewGL2D
Promise<TessellatedMesh>

Tessellate an Extent into a rectangle.

more details
BaseLayerViewGL2D
Promise<TessellatedMesh>

Tessellate a Multipoint into quads (markers).

more details
BaseLayerViewGL2D
Promise<TessellatedMesh>

Tessellate a Point into a quad (marker).

more details
BaseLayerViewGL2D
Promise<TessellatedMesh>

Tessellate a Polygon into triangles.

more details
BaseLayerViewGL2D
Promise<TessellatedMesh>

Tessellate a Polyline into triangles.

more details
BaseLayerViewGL2D

Method to implement, which notifies of tiles being added or removed for the current view state.

more details
BaseLayerViewGL2D
Promise

when() may be leveraged once an instance of the class is created.

more details
LayerView

Method Details

addHandles(handleOrHandles, groupKey)inherited
Since: ArcGIS Maps SDK for JavaScript 4.25

Adds one or more handles which are to be tied to the lifecycle of the object. The handles will be removed when the object is destroyed.

// Manually manage handles
const handle = reactiveUtils.when(
  () => !view.updating,
  () => {
    wkidSelect.disabled = false;
  },
  { once: true }
);

// Handle gets removed when the object is destroyed.
this.addHandles(handle);
Parameters
handleOrHandles WatchHandle|WatchHandle[]

Handles marked for removal once the object is destroyed.

groupKey *
optional

Key identifying the group to which the handles should be added. All the handles in the group can later be removed with Accessor.removeHandles(). If no key is provided the handles are added to a default group.

attach()

Method called after the LayerView is created and right before it starts drawing the layer's content. Typically this method is implemented to start watching property changes on the layer and to initialize WebGL objects such as shaders.

See also
Example
// Create a shader program and a property watcher
attach() {
  let gl = this.context;

  this._shaderProgram = gl.createProgram();
  ...

  this._propertyHandle = this.layer.watch("opacity", function() {
    this.requestRender();
  });
}
bindRenderTarget()

Bind the designated rendering output surface and restore the correct viewport.

This method can be used after the WebGL state has been altered by a call to gl.bindFramebuffer() to restore the framebuffer that contains the final, composited frame, i.e. the one that is guaranteed to be bound right before control is handed over to render(). Note that this may or may not be the default framebuffer; MapView can use various surfaces for frame compositing and there is no guarantee that when render() is called, the bound framebuffer is the default one.

Together with the framebuffer, also a matching full-size viewport is restored.

Example
render() {
  let gl = this.context;

  ...

  // Bind a temporary offscreen surface
  gl.bindFramebuffer(gl.FRAMEBUFFER, this.myOffscreenSurface);

  ...

  // Render to the offscreen surface

  ...

  // Bind the original render surface so that the image stored
  // into the temporary one can be blitted/composited with the
  // actual frame data
  this.bindRenderTarget();

  ...

  // Your own frame composition logic

  ...
}
detach()

Method called after the layer is removed and the LayerView is about to be removed. Typically, this method is implemented to free resources like watchers and destroy WebGL objects such as shader programs.

See also
Example
// Remove the watchers and destroy the shader program created in attach()
detach() {
  this._propertyHandle.remove();
  this._propertyHandle = null;

  const gl = this.context;

  gl.deleteProgram(this._shaderProgram);
  this._shaderProgram = null;
}
getRenderTarget(){RenderTarget}

Get the designated rendering output surface and corresponding viewport configuration.

The returned object is the same render target that is restored by a call to bindRenderTarget().

Returns
Type Description
RenderTarget
hasHandles(groupKey){Boolean}inherited
Since: ArcGIS Maps SDK for JavaScript 4.25

Returns true if a named group of handles exist.

Parameter
groupKey *
optional

A group key.

Returns
Type Description
Boolean Returns true if a named group of handles exist.
Example
// Remove a named group of handles if they exist.
if (obj.hasHandles("watch-view-updates")) {
  obj.removeHandles("watch-view-updates");
}
hitTest(mapPoint, screenPoint){Promise<Graphic[]>}

Method to implement that is responsible for providing objects hit at the specified screen coordinates. This method is called internally by the MapView each time its hitTest() method is called.

Parameters
mapPoint Point

The point in map units.

screenPoint ScreenPoint

The point in screen coordinates.

Returns
Type Description
Promise<Graphic[]> A Promise that resolves to an array of graphics.
isFulfilled(){Boolean}inherited

isFulfilled() may be used to verify if creating an instance of the class is fulfilled (either resolved or rejected). If it is fulfilled, true will be returned.

Returns
Type Description
Boolean Indicates whether creating an instance of the class has been fulfilled (either resolved or rejected).
isRejected(){Boolean}inherited

isRejected() may be used to verify if creating an instance of the class is rejected. If it is rejected, true will be returned.

Returns
Type Description
Boolean Indicates whether creating an instance of the class has been rejected.
isResolved(){Boolean}inherited

isResolved() may be used to verify if creating an instance of the class is resolved. If it is resolved, true will be returned.

Returns
Type Description
Boolean Indicates whether creating an instance of the class has been resolved.
removeHandles(groupKey)inherited
Since: ArcGIS Maps SDK for JavaScript 4.25

Removes a group of handles owned by the object.

Parameter
groupKey *
optional

A group key or an array or collection of group keys to remove.

Example
obj.removeHandles(); // removes handles from default group

obj.removeHandles("handle-group");
obj.removeHandles("other-handle-group");
render(renderParameters)

The method to implement that is responsible of drawing the content of the layer. This method is called every time the MapView's state changes, or if requestRender() has been called.

Parameters
Specification
renderParameters Object
Specification

The WebGL or WebGL 2 context. Its concrete type depends on system configuration. Every time that render() is called, the API automatically resets WebGL to a conventional state which is almost the default one; the only two things that may be non-default are the bound framebuffer and the viewport, which is set to match the entire framebuffer. The body of render() must not change these settings.

stationary Boolean

The stationary state of the MapView.

state ViewState

The object that describes view state.

Example
// Example of a render implementation that draws using a custom shader program
render(renderParameters) {
  const gl = this.context;
  gl.bindBuffer(gl.ARRAY_BUFFER, this._vertexBuffer);
  gl.vertexAttribPointer(0, 2, gl.SHORT, false, 10, 0);
  gl.vertexAttribPointer(1, 3, gl.SHORT, true, 10, 4);
  gl.bindBuffer(gl.ARRAY_BUFFER, null);
  gl.enableVertexAttribArray(0);
  gl.enableVertexAttribArray(1);
  ...
  // Update uniforms as needed by calling gl.uniform...
  ...
  gl.useProgram(this._shaderProgram);
  gl.drawArrays(gl.TRIANGLES, 0, this._vertexCount);
  gl.disableVertexAttribArray(0);
  gl.disableVertexAttribArray(1);
  gl.useProgram(null);
}
requestRender()

The LayerView can call this method to ask the MapView to schedule a new rendering frame.

Example
// Call requestRender whenever the layer opacity has changed
attach() {
  this._propertyHandle = this.layer.watch("opacity", function() {
    this.requestRender();
  });
}
tessellateExtent(extent){Promise<TessellatedMesh>}
Since: ArcGIS Maps SDK for JavaScript 4.14

Tessellate an Extent into a rectangle.

Parameter
extent Extent

The input geometry.

Returns
Type Description
Promise<TessellatedMesh>
Example
this.tessellateExtent(g.geometry).then(function (mesh) {
   // do something with mesh
 });
tessellateMultipoint(multipoint, footprint){Promise<TessellatedMesh>}
Since: ArcGIS Maps SDK for JavaScript 4.14

Tessellate a Multipoint into quads (markers).

Parameters
multipoint Multipoint

The input geometry. These are the geographic points where each marker will me anchored.

footprint Rect

The rectangle that describes the geometry of each marker. Coordinates x and y can be thought as being in screen-space, relative to the screen-space projection of the geographic point.

Returns
Type Description
Promise<TessellatedMesh>
Example
this.tessellateMultipoint(g.geometry, {x: 0, : -12, width: 34, height: 10}).then(function (mesh) {
   // do something with mesh
 });
tessellatePoint(point, footprint){Promise<TessellatedMesh>}
Since: ArcGIS Maps SDK for JavaScript 4.14

Tessellate a Point into a quad (marker).

Parameters
point Point

The input geometry. This is the geographic point where the marker will me anchored.

footprint Rect

The rectangle that describes the geometry of the marker. Coordinates x and y are the position of the upper-left corner of the marker, and can be thought as being in screen-space, relative to the screen-space projection of the geographic point; width and height are in pixels. See Rect for a visual explanation of marker geometry.

Returns
Type Description
Promise<TessellatedMesh>
  • A promise to a TessellatedMesh. The output mesh is composed of two triangles.
Example
this.tessellatePoint(g.geometry, {x: 0, : -12, width: 34, height: 10}).then(function (mesh) {
   // do something with mesh
 });
tessellatePolygon(polygon){Promise<TessellatedMesh>}
Since: ArcGIS Maps SDK for JavaScript 4.14

Tessellate a Polygon into triangles.

Parameter
polygon Polygon

The input geometry. The geometry must be simple; if the input geometry is not simple, you must first create a simplified version of it using geometryEngine, and pass the simplified geometry to tessellatePolygon.

Returns
Type Description
Promise<TessellatedMesh>
Example
this.tessellatePolygon(g.geometry).then(function (mesh) {
   // do something with mesh
 });
tessellatePolyline(polyline, width){Promise<TessellatedMesh>}
Since: ArcGIS Maps SDK for JavaScript 4.14

Tessellate a Polyline into triangles.

Parameters
polyline Polyline

The input geometry. The geometry must be simple; if the input geometry is not simple, you must first create a simplified version of it using geometryEngine, and pass the simplified geometry to tessellatePolyline.

width Number

The width of the line; this will be used to scale xOffset and yOffset.

Returns
Type Description
Promise<TessellatedMesh>
Example
this.tessellatePolyline(g.geometry, 10).then(function (mesh) {
   // do something with mesh
 });
tilesChanged(added, removed)

Method to implement, which notifies of tiles being added or removed for the current view state. This function can be implemented to start and stop fetching new data, or allocate and dispose resources.

Parameters
added Tile[]

The tile objects added for the current view viewport.

removed Tile[]

The tile objects removed from the view viewport.

when(callback, errback){Promise}inherited

when() may be leveraged once an instance of the class is created. This method takes two input parameters: a callback function and an errback function. The callback executes when the instance of the class loads. The errback executes if the instance of the class fails to load.

Parameters
callback Function
optional

The function to call when the promise resolves.

errback Function
optional

The function to execute when the promise fails.

Returns
Type Description
Promise Returns a new promise for the result of callback that may be used to chain additional functions.
Example
// Although this example uses MapView, any class instance that is a promise may use when() in the same way
let view = new MapView();
view.when(function(){
  // This function will execute once the promise is resolved
}, function(error){
  // This function will execute if the promise is rejected due to an error
});

Type Definitions

MeshVertex Object

A vertex of a tessellated mesh.

There are five different tessellation algorithms, one for each supported geometry type. The attributes in a vertex can be used to populate vertex and index buffers that can be rendered using appropriate shaders. See the SDK sample for a possible way of doing this using a single universal shader program that can render any of the supported geometry types.

There are four attributes; the first three are 2D points, and the last one is a scalar value. In total a mesh vertex contains 7 numeric values.

Geographic position (x, y) The geographic point associated to that vertex. For Extent and Polygon is equivalent to the position of the vertex itself; for Point and Multipoint is the geographic position of the point, and the anchor that will be associated to the corresponding marker symbol; for Polyline it lies on the centerline. The geographic position is usually expressed in map units and a custom vertex shader will generally need to transform it to normalized device coordinates.

Offset vector (xOffset, yOffset) This is an offset that is generally expressed in units other than the view's ones, and drives the extrusion of the geographic position into lines and quads. For Extent and Polygon is zero; for Point and Multipoint it goes from the anchor to the four vertices of the quad on screen; for Polyline it goes from the centerline to a vertex on the polyline's edge. The offset vector is usually expressed in some other units than map and will not need to be transformed by the same transform used for the geographic position. A common convention is to express the offset in points or pixels and code the vertex shader accordingly.

tessellation-helpers-extrusion

Texture coordinates (uTexcoord, vTexcoord) The texture coordinates associated to this vertex. For Extent the lower left vertex has coordinates (0, 0) and the upper right (1, 1); for Polygon the coordinates at each vertex match the interpolated coordinates that the smallest enclosing extent for that polygon would have at the same fragment; for Point and Multipoint each quad has (0, 0) as the lower left texture coordinate and (1, 1) as the upper right one; for Polyline the start cap is made of two vertices with texture coordinates (0, 0) and (0, 1) while the end cap is associated to (1, 0) and (1, 1).

tessellation-helpers-uv

Distance Valid only for Polyline; it is the distance, in map units, from the beginning of the polyline to this vertex.

tessellation-helpers-distance

Properties
x Number

The x-coordinate, expressed in the same units as the MapView.

y Number

The y-coordinate, expressed in the same units as the MapView.

xOffset Number

The x-offset in screen space; this is used to extrude points (into quads) and polylines, and is 0 for polygons.

yOffset Number

The y-offset in screen space; this is used to extrude points (into quads) and polylines, and is 0 for polygons.

uTexcoord Number

The u-coordinate for texture mapping. It varies between 0 and 1 horizontally for quads and polygons, and along the entire length of a polyline.

vTexcoord Number

The v-coordinate for texture mapping. It varies between 0 and 1 vertically for quads and polygons, and across the width of a polyline.

distance Number

The distance parameter for this vertex; this only applies when tessellating polylines. It starts from 0 and runs up to the total length of the polyline. It is expressed in map units.

Rect Object

A rectangle in screen-space.

An instance of Rect is used to specify the screen-space geometry of the resulting marker when calling BaseLayerViewGL2D or BaseLayerViewGL2D. The exact interpretation of "screen-space" is ultimately implemented through a custom vertex shader; a common convention is to interpret the values in the rect as being expressed in pixels or points. See BaseLayerViewGL2D for more details.

tessellation-helpers-uv

Properties
x Number

The x-coordinate of the upper-left corner of the rectangle, relative to the anchor of the marker.

y Number

The y-coordinate of the upper-left corner of the rectangle, relative to the anchor of the marker.

width Number

Width of the rectangle.

height Number

Height of the rectangle.

RenderTarget Object

The destination to which render() should direct its output.

Rendering output is saved into a framebuffer, possibly but not necessarily the default one, at a location defined by the viewport.

An instance of this class is mantained internally by BaseLayerViewGL2D and can be accessed by a call to getRenderTarget(). It is the same instance that is restored to the WebGL context by calling bindRenderTarget().

When control is handed over to render(), the WebGL context is guaranteed to be in a default state except for the currently bound framebuffer and the configured viewport. Implementations of render() are free to change these parameters using gl.bindFramebuffer() and gl.viewport(), but they must send the output of the rendering process to the render target.

Properties
framebuffer WebGLFramebuffer

The framebuffer where the render() method should direct its output.

viewport Number[]

A viewport that fully covers framebuffer.

ScreenPoint

An object representing a point on the screen.

Properties
x Number

The x coordinate.

y Number

The y coordinate.

TessellatedMesh Object

The triangle mesh resulting from a tessellation operation.

An instance of Mesh can be obtained by calling one of the BaseLayerViewGL2D tessellate* methods and passing an instance of Geometry.

Properties
vertices MeshVertex[]

The vertices that make up the mesh. Each element is a BaseLayerViewGL2D.

indices Number[]

The indices of the triangles that connect vertices together; each consecutive triplet of indices denotes a triangle.

Tile Object

Represents a tile reference.

Properties
id String

The tile string identifier in the format level/row/col/world

level Number

The level identifier of the LOD to which the tile belongs

row Number

The row identifier.

col Number

The column identifier.

world Number

When the projection allows world wrapping (e.g. Web Mercator), identifies the instance of the world this tile's level/row/col.

resolution Number

The number of map units per pixel in the tile.

scale Number

The map scale at the tile's level.

coords Number[]

The coordinates of the top-left corner of the tile as an array of two numbers. The coordinates are in un-normalized map units.

bounds Number[]

The bounds of the tile as an array of four numbers that be readily converted to an Extent object.

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