From b138acad1061e400d23843d6735bcd91d7d44ae0 Mon Sep 17 00:00:00 2001 From: HARPER Jon Date: Sun, 8 Oct 2023 19:09:42 +0200 Subject: [PATCH] Improvements for react-map-gl docs Remove all mentions of react-map-gl v5/v6, assume v7 use relative links for ../../api-reference no longer recommend MapboxLayer unless specific constraints require it --- .../developer-guide/base-maps/using-with-mapbox.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/developer-guide/base-maps/using-with-mapbox.md b/docs/developer-guide/base-maps/using-with-mapbox.md index b76bce1a031..e18d5ae3a8e 100644 --- a/docs/developer-guide/base-maps/using-with-mapbox.md +++ b/docs/developer-guide/base-maps/using-with-mapbox.md @@ -6,11 +6,11 @@ [Mapbox GL JS](https://github.com/mapbox/mapbox-gl-js) is a powerful open-source map renderer from [Mapbox](https://mapbox.com). deck.gl's `MapView` is designed to sync perfectly with the camera of Mapbox, at every zoom level and rotation angle. -When using deck.gl and Mapbox, there are three options you can choose from, first based on which library handles all user input and holds the source of truth of the camera state (dictating which is the root component), and second how the content from both libraries interact (allowing simple overlaying or requiring complex interleaving). +When using deck.gl and Mapbox, there are three options you can choose from, first based on which library handles all user input and holds the source of truth of the camera state (dictating which is the root component), and second how the content from both libraries interact (allowing simple overlaying or requiring complex interleaving and gl context sharing). -- If you don't use the most advanced features of Deck such as non-mercator projection or terrain, and if you want to use basic mapbox-gl controls (e.g. `NavigationControl`) or plugins in addition to deck.gl while using the latest version of react-map-gl v7, then you have to use Mapbox as the root element. The recommended approach is then to use the Deck canvas as an overlay on top of the basemap, inserted into the map container using [MapboxOverlay](https://deck.gl/docs/api-reference/mapbox/mapbox-overlay#using-with-react-map-gl) in its default mode (overlaid). The [vanilla JS get-started example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/pure-js/mapbox/) illustrates this pattern. -- Otherwise, if you are fine with using previous versions of react-map-gl or not using mapbox-gl controls at all, then the recommended approach is to use Deck as the root element with its canvas as an overlay on top of the child Mapbox map. The [React get-started example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/react/mapbox/) illustrates the basic pattern using react-map-gl v5/v6 APIs. This is the most tested and robust use case with respect to Deck's functionality, as you can find in all the [examples on this website](https://deck.gl/examples/). It supports all the most advanced features of Deck. -- Finally, if you need to mix deck.gl layers with base map layers, e.g. having deck.gl surfaces below text labels or objects occluding each other correctly in 3D, then you have to use deck.gl layers interleaved with Mapbox layers in the same WebGL context. In addition to using Mapbox as the root element, you have to use either the `MapboxOverlay` in interleaved mode or `MapboxLayer` from the [@deck.gl/mapbox](../../api-reference/mapbox/overview.md) module. Be cautious that this feature subjects to bugs and limitations of mapbox-gl's custom layer interface. Here's an [interactive example](https://deck.gl/examples/mapbox), and in the following image, notice that the yellow circles (first deck.gl layer) are between the ground (first mapbox layer) and the labels (second mapbox layer) and also below the buildings (third mapbox layer) which correctly occlude the arcs (second deck.gl layer) +- If you don't use the most advanced features of Deck, such as multi-view and effects, and want to use all the features of mapbox-gl, such as controls like `NavigationControl` or plugins, then you have to use Mapbox as the root element. The recommended approach is then to use the Deck canvas as an overlay on top of the basemap, inserted into the map container using [MapboxOverlay](../../api-reference/mapbox/mapbox-overlay#using-with-react-map-gl) from the [@deck.gl/mapbox](../../api-reference/mapbox/overview.md) module in its default mode (overlaid, which corresponds to interleaved: false). The [react get-started example](https://github.com/visgl/deck.gl/tree/master/examples/get-started/react/mapbox/) illustrates this pattern. +- Otherwise, if you need the more advanced features of Deck, then the recommended approach is to use Deck as the root element with its canvas as an overlay on top of the child Mapbox map. The [Minimap example](https://deck.gl/examples/multi-view) illustrates the basic pattern. This is the most tested and robust use case with respect to Deck's functionality, but you can't use all the features of mapbox-gl like controls (e.g. `NavigationControl`) and plugins. +- Finally, if you need to mix deck.gl layers with base map layers, e.g. having deck.gl surfaces below text labels or objects occluding each other correctly in 3D, then you have to use deck.gl layers interleaved with Mapbox layers in the same WebGL context. In addition to using Mapbox as the root element, you have to use `MapboxOverlay` in interleaved mode (interleaved: true). Be cautious that this feature subjects to bugs and limitations of mapbox-gl's custom layer interface. Here's an [interactive example](https://deck.gl/examples/mapbox), and in the following image, notice that the yellow circles (first deck.gl layer) are between the ground (first mapbox layer) and the labels (second mapbox layer) and also below the buildings (third mapbox layer) which correctly occlude the arcs (second deck.gl layer) ![deck.gl interleaved with Mapbox layers](https://raw.github.com/visgl/deck.gl-data/master/images/whats-new/mapbox-layers.jpg) @@ -20,11 +20,13 @@ When using deck.gl and Mapbox, there are three options you can choose from, firs All the [examples on this website](https://github.com/visgl/deck.gl/tree/master/examples/website) are implemented using the React integration. -When you choose the react-map-gl `Map` React component as the root component, using [MapboxOverlay](https://deck.gl/docs/api-reference/mapbox/mapbox-overlay#using-with-react-map-gl) with react-map-gl `useControl` or [MapboxLayer](https://deck.gl/docs/api-reference/mapbox/mapbox-layer#example) works especially well to insert perfectly synchronized deckgl layers in the map container. +When you choose the react-map-gl `Map` React component as the root component, using [MapboxOverlay](../../api-reference/mapbox/mapbox-overlay#using-with-react-map-gl) with react-map-gl `useControl` works especially well to insert perfectly synchronized deckgl layers in the map container. When you choose the `DeckGL` React component as the root component, react-map-gl [Map](https://visgl.github.io/react-map-gl/docs/api-reference/map) as a child automatically interprets the deck.gl view state (i.e. latitude, longitude, zoom etc). In this configuration your deck.gl layers will still render as a perfectly synchronized geospatial overlay over the underlying map. -> Unfortunately, as noted at the begining of this page, using `DeckGL` as the root component is not compatible with `react-map-gl` v7's controls (`NavigationControl`, `GeolocateControl` etc.) because of `react-map-gl` decisions to prioritize its own maintainability, performance, and compatibility when used standalone. However, it is still possible with the v5 and v6 previous `react-map-gl` versions since the controls can be used with or without a base map. See [ContextProvider](../../api-reference/react/deckgl.md#contextprovider) for an example. +> Unfortunately, as noted at the begining of this page, using `DeckGL` as the root component is not compatible with `react-map-gl` controls (`NavigationControl`, `GeolocateControl` etc.) because of `react-map-gl` decisions to prioritize its own maintainability, performance, and compatibility when used standalone. + +> If you are constrained to using mapbox layers instead of a mapbox control, you can use [MapboxLayer](../../api-reference/mapbox/mapbox-layer#example) but in the general use case it is no longer recommended. Its functionality can be fully replaced by [MapboxOverlay](../../api-reference/mapbox/mapbox-overlay#using-with-react-map-gl) with interleaved: true ## Using Mapbox basemap service (with Mapbox token)