diff --git a/docs/api-reference/mapbox/mapbox-layer.md b/docs/api-reference/mapbox/mapbox-layer.md index 5f3c2ff91ab..c75a6fde79b 100644 --- a/docs/api-reference/mapbox/mapbox-layer.md +++ b/docs/api-reference/mapbox/mapbox-layer.md @@ -1,6 +1,6 @@ # MapboxLayer -`MapboxLayer` is an implementation of [mapbox](https://www.npmjs.com/package/mapbox-gl)'s custom layer API. By adding a `MapboxLayer` instance to an mapbox map, one can render any deck.gl layer inside the mapbox canvas / WebGL context. This is in contrast to the traditional deck.gl/mapbox integration where the deck.gl layers are rendered into a separate canvas over the base map. +`MapboxLayer` is an implementation of [Mapbox GL JS](https://www.npmjs.com/package/mapbox-gl)'s [CustomLayerInterface](https://docs.mapbox.com/mapbox-gl-js/api/properties/#customlayerinterface) API. By adding a `MapboxLayer` instance to an mapbox map, one can render any deck.gl layer inside the mapbox canvas / WebGL context. This is in contrast to the traditional deck.gl/mapbox integration where the deck.gl layers are rendered into a separate canvas over the base map. See [mapbox documentation](https://www.mapbox.com/mapbox-gl-js/api/#map#addlayer) for how to add a layer to an existing layer stack. diff --git a/docs/api-reference/mapbox/mapbox-overlay.md b/docs/api-reference/mapbox/mapbox-overlay.md new file mode 100644 index 00000000000..6da4f7bba8a --- /dev/null +++ b/docs/api-reference/mapbox/mapbox-overlay.md @@ -0,0 +1,63 @@ +# MapboxOverlay + +`MapboxOverlay` is an implementation of [Mapbox GL JS](https://www.npmjs.com/package/mapbox-gl)'s [IControl](https://docs.mapbox.com/mapbox-gl-js/api/markers/#icontrol) API. When adding a `MapboxOverlay` instance to an mapbox map, a deck.gl canvas overlaid on top of the base map, and synchronized with the map's camera. + +## Example + +```js +import {MapboxOverlay} from '@deck.gl/mapbox'; +import {ScatterplotLayer} from '@deck.gl/layers'; + +const map = new mapboxgl.Map({...}); + +const overlay = new MapboxOverlay({ + layers: [ + new ScatterplotLayer({ + id: 'my-scatterplot', + data: [ + {position: [-74.5, 40], size: 100} + ], + getPosition: d => d.position, + getRadius: d => d.size, + getColor: [255, 0, 0] + }) + ] +}); + +map.addControl(overlay); +``` + +## Constructor + +```js +import {MapboxOverlay} from '@deck.gl/mapbox'; +new MapboxOverlay(props); +``` + +`MapboxOverlay` accepts the same props as the [Deck](/docs/api-reference/core/deck.md) class, with the following exceptions: + +- `views` - multi-view is not supported. There is only one `MapView` that synchronizes with the base map. +- `viewState` - managed internally. +- `controller` - always disabled (to use Mapbox's interaction handlers). + +## Methods + +##### setProps + +Updates (partial) props of the underlying `Deck` instance. See [Deck.setProps](/docs/api-reference/core/deck.md#setprops). + +##### pickObject + +See [Deck.pickObject](/docs/api-reference/core/deck.md#pickobject). + +##### pickObjects + +See [Deck.pickObjects](/docs/api-reference/core/deck.md#pickobjects). + +##### pickMultipleObjects + +See [Deck.pickMultipleObjects](/docs/api-reference/core/deck.md#pickmultipleobjects). + +##### finalize + +Removes the control and deletes all resources. diff --git a/examples/get-started/pure-js/mapbox/app.js b/examples/get-started/pure-js/mapbox/app.js index 2ece91ade49..743c6b296b4 100644 --- a/examples/get-started/pure-js/mapbox/app.js +++ b/examples/get-started/pure-js/mapbox/app.js @@ -1,4 +1,4 @@ -import {Deck} from '@deck.gl/core'; +import {MapboxOverlay as DeckOverlay} from '@deck.gl/mapbox'; import {GeoJsonLayer, ArcLayer} from '@deck.gl/layers'; import mapboxgl from 'mapbox-gl'; @@ -6,41 +6,16 @@ import mapboxgl from 'mapbox-gl'; const AIR_PORTS = 'https://d2ad6b4ur7yvpq.cloudfront.net/naturalearth-3.3.0/ne_10m_airports.geojson'; -const INITIAL_VIEW_STATE = { - latitude: 51.47, - longitude: 0.45, +const map = new mapboxgl.Map({ + container: 'map', + style: 'https://basemaps.cartocdn.com/gl/positron-nolabels-gl-style/style.json', + center: [0.45, 51.47], zoom: 4, bearing: 0, pitch: 30 -}; - -const MAP_STYLE = 'https://basemaps.cartocdn.com/gl/positron-nolabels-gl-style/style.json'; - -const map = new mapboxgl.Map({ - container: 'map', - style: MAP_STYLE, - // Note: deck.gl will be in charge of interaction and event handling - interactive: false, - center: [INITIAL_VIEW_STATE.longitude, INITIAL_VIEW_STATE.latitude], - zoom: INITIAL_VIEW_STATE.zoom, - bearing: INITIAL_VIEW_STATE.bearing, - pitch: INITIAL_VIEW_STATE.pitch }); -export const deck = new Deck({ - canvas: 'deck-canvas', - width: '100%', - height: '100%', - initialViewState: INITIAL_VIEW_STATE, - controller: true, - onViewStateChange: ({viewState}) => { - map.jumpTo({ - center: [viewState.longitude, viewState.latitude], - zoom: viewState.zoom, - bearing: viewState.bearing, - pitch: viewState.pitch - }); - }, +const deckOverlay = new DeckOverlay({ layers: [ new GeoJsonLayer({ id: 'airports', @@ -71,3 +46,6 @@ export const deck = new Deck({ }) ] }); + +map.addControl(deckOverlay); +map.addControl(new mapboxgl.NavigationControl()); diff --git a/examples/get-started/pure-js/mapbox/index.html b/examples/get-started/pure-js/mapbox/index.html index 71054d1f85e..b35787c9cc8 100644 --- a/examples/get-started/pure-js/mapbox/index.html +++ b/examples/get-started/pure-js/mapbox/index.html @@ -4,28 +4,18 @@