Update docs about base map usage (visgl#5907)

docs/api-reference/core/deckgl.md

@@ -49,9 +49,11 @@ The scripting API offers out-of-the-box integration with Mapbox. To add a base m
 <link href='https://api.tiles.mapbox.com/mapbox-gl-js/v0.53.0/mapbox-gl.css' rel='stylesheet' />
 ```
 
+The above script adds `mapboxgl` to the global scope, which will be picked up by default. 
+
 To disable the base map, simply exclude the mapbox script or set `map` to false.
 
-`map` is default to the global variable `mapboxgl`. In some environments such as Observable, libraries cannot be imported into the global scope, in which case you need to manually pass the mapboxgl object to `map`:
+In some environments such as Observable, libraries cannot be imported into the global scope, in which case you need to manually pass the mapboxgl object to `map`:
 
 ```js
 mapboxgl = require('mapbox-gl@~0.44.1/dist/mapbox-gl.js');
@@ -66,6 +68,22 @@ new deck.DeckGL({
 });
 ```
 
+To use a mapbox-gl fork such as [MapLibre GL JS](https://maplibre.org), pass the corresponding library entry point to `map`:
+
+```html
+<script src="https://unpkg.com/maplibre-gl@latest/dist/maplibre-gl.js"></script>
+<link href="https://unpkg.com/maplibre-gl@latest/dist/maplibre-gl.css" rel="stylesheet" />
+```
+
+And 
+
+```js
+new deck.DeckGL({
+  ...
+  map: maplibregl
+});
+```
+
 ##### `mapStyle` (Object | String)
 
 The style JSON or URL for the Mapbox map.

docs/get-started/using-with-map.md

@@ -2,12 +2,31 @@
 
 While deck.gl works independently without any map component, when visualizing geospatial datasets, a base map can offer the invaluable context for understanding the overlay layers.
 
-deck.gl has been designed to work in tandem with popular JavaScript base map providers, especially Mapbox. Depending on your tech stack, deck.gl's support for a particular base map solution may come with different level of compatibility and limitations.
+deck.gl has been designed to work in tandem with popular JavaScript base map providers. Depending on your tech stack, deck.gl's support for a particular base map solution may come with different level of compatibility and limitations.
 
-In this document you will find how to use deck.gl with different providers and technologies. It is important to understand the difference between the JS library rendering and the basemap provider itself. For example you can use MapboxGL with Mapbox basemaps, but also with any other basemap provider that provides Mapbox Vector Tiles.
+There are two types of integration between deck.gl and a base map solution:
 
-When using different basemaps you have to be sure to follow the terms and conditions of each service and their attribution requirements.
+- **Overlaid**: the Deck canvas is rendered over the base map as a separate DOM element. Deck's camera and the camera of the base map are synchronized so they pan/zoom together. This is the more robust option since the two libraries manage their renderings independently from each other. It is usually sufficient if the base map is 2D.
 
+![Deck as overlay on top of the base map](https://miro.medium.com/max/1600/0*K3DVssEhnv5VaDCp)
+
+- **Interleaved**: Deck renders into the WebGL context of the base map. This allows for occlusion between deck.gl layers and the base map's labels and/or 3D features. The availability of this option depends on whether the base map solution exposes certain developer APIs, and may subject the user to bugs/limitations associated with such APIs.
+
+![Deck interleaved with base map layers](https://miro.medium.com/max/1600/0*faYL1UbVD4af5qzy)
+
+
+| Library | Pure JS | React | Overlaid | Interleaved |
+| ----- | ----- | ----- | ----- | ----- |
+| [Mapbox GL JS](https://docs.mapbox.com/mapbox-gl-js/api/) | ✓ | ✓ | [example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/pure-js/mapbox) | [example](https://deck.gl/gallery/mapbox-layer) |
+| [MapLibre GL JS](https://maplibre.org/maplibre-gl-js-docs/api/) | ✓ | ✓ | [example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/pure-js/mapbox) | [example](https://deck.gl/gallery/mapbox-layer) |
+| [Google Maps JavaScript API](https://developers.google.com/maps/documentation/javascript/overview) | ✓ |  | [example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/pure-js/google-maps) | 
+| [ArcGIS API for JavaScript](https://developers.arcgis.com/javascript/latest/) | ✓ | ✓ | | [example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/pure-js/arcgis) |
+| [harp.gl](https://www.harp.gl/) | ✓ | | [example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/pure-js/harp.gl) |  |
+| [Leaflet](https://leafletjs.com/) | ✓ | | [example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/pure-js/leaflet) |  |
+
+It is also important to understand the difference between the JS library that renders the map and the map data provider. For example, you can use Mapbox GL JS with the Mapbox service, but also with any other service that hosts Mapbox Vector Tiles. When using a base map, be sure to follow the terms and conditions, as well as the attribution requirements of both the JS library and the data provider.
+
+Read on for notes on provider-specific support.
 
 ## Using deck.gl with Mapbox GL JS
 
@@ -18,8 +37,7 @@ When using deck.gl and Mapbox, there are two options you can choose from:
 - Using the Deck canvas as a overlay on top of the Mapbox map, in [pure JS](https://github.com/visgl/deck.gl/tree/master/examples/get-started/pure-js/mapbox) or [React](https://github.com/visgl/deck.gl/tree/master/examples/get-started/react/mapbox). This is the most tested and robust use case.
 - Using deck.gl layers as custom Mapbox layers, using the [@deck.gl/mapbox](/docs/api-reference/mapbox/overview.md) module. This allows you to interleave deck.gl layers with base map layers, e.g. below text labels or occlude each other correctly in 3D. Be cautious that this feature is experimental: we are working closely with Mapbox to evolve the API.
 
-<img src="https://raw.github.com/visgl/deck.gl-data/master/images/whats-new/mapbox-layers.jpg" />
-
+![deck.gl interleaved with Mapbox layers](https://raw.github.com/visgl/deck.gl-data/master/images/whats-new/mapbox-layers.jpg)
 
 ### react-map-gl
 
@@ -63,12 +81,30 @@ Some useful resources for creating your own map service:
 - [Open source tools](https://github.com/mapbox/awesome-vector-tiles)
 - [Maputnik Style editor](https://maputnik.github.io)
 
+### Compatibility with Mapbox GL JS forks
+
+As of v2.0, Mapbox GL JS [went proprietary](https://github.com/mapbox/mapbox-gl-js/blob/main/CHANGELOG.md#200) and requires a Mapbox account to use even if you don't load tiles from the Mapbox data service. Community forks of the v1 code base such as [MapLibre GL JS](https://maplibre.org) can generally be used as a drop-in replacement of mapbox-gl. If you are using react-map-gl, follow [these instructions](http://visgl.github.io/react-map-gl/docs/get-started/get-started#using-with-a-mapbox-gl-fork).
+
+If the forked libraries and Mapbox API diverge in the future, compatibility issues may arise. deck.gl intends to support open source efforts wherever reasonable. Please report any issue on GitHub.
+
+
 ## Using deck.gl with Google Maps
 
-Starting v7.0, deck.gl has experimental support for Google Maps with the [@deck.gl/google-maps](/docs/api-reference/google-maps/overview.md) module. It allows you to construct a Deck instance as a custom Google Maps [OverlayView](https://developers.google.com/maps/documentation/javascript/reference/#OverlayView).
+Starting with v7.0, deck.gl has support for Google Maps with the [@deck.gl/google-maps](/docs/api-reference/google-maps/overview.md) module. It allows you to construct a Deck instance as a custom Google Maps [OverlayView](https://developers.google.com/maps/documentation/javascript/reference/#OverlayView).
 
-<img src="https://raw.github.com/visgl/deck.gl-data/master/images/whats-new/google-maps.jpg" />
+![deck.gl as a Google Maps overlay](https://raw.github.com/visgl/deck.gl-data/master/images/whats-new/google-maps.jpg)
 
 The Deck canvas can only be used as a overlay on top of Google Maps, see [pure JS example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/pure-js/google-maps). Tilting is not supported due to Google Maps API restrictions. See module documentation page for a full list of features.
 
 Note that to run the examples, you need a [Google Maps API key](https://developers.google.com/maps/documentation/javascript/get-api-key).
+
+
+## Using deck.gl with ArcGIS
+
+Starting with v8.1, deck.gl has support for ArcGIS with the [@deck.gl/arcgis](/docs/api-reference/arcgis/overview.md) module.
+
+![deck.gl as a ArcGIS map layer](https://raw.github.com/visgl/deck.gl-data/master/images/whats-new/arcgis.jpg)
+
+2D integration with `MapView` is supported by the [DeckLayer](/docs/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](/docs/api-reference/arcgis/deck-renderer.md) class.