1"use strict";(self.webpackChunkproject_website=self.webpackChunkproject_website||[]).push([["1642"],{6331(e,n,a){a.r(n),a.d(n,{metadata:()=>r,default:()=>x,frontMatter:()=>t,contentTitle:()=>c,toc:()=>p,assets:()=>d});var r=JSON.parse('{"id":"api-reference/mapbox/mapbox-overlay","title":"MapboxOverlay","description":"MapboxOverlay is an implementation of Mapbox GL JS\'s IControl API. When adding a MapboxOverlay control to an mapbox map, deck.gl layers are rendered in synchronization with the base map layers. This control supports both overlaid and interleaved rendering modes.","source":"@site/../docs/api-reference/mapbox/mapbox-overlay.md","sourceDirName":"api-reference/mapbox","slug":"/api-reference/mapbox/mapbox-overlay","permalink":"/docs/api-reference/mapbox/mapbox-overlay","draft":false,"unlisted":false,"editUrl":"https://github.com/visgl/deck.gl/tree/master/website/../docs/api-reference/mapbox/mapbox-overlay.md","tags":[],"version":"current","frontMatter":{},"sidebar":"tutorialSidebar","previous":{"title":"@deck.gl/mapbox","permalink":"/docs/api-reference/mapbox/overview"},"next":{"title":"MapLibreOverlay","permalink":"/docs/api-reference/maplibre/overview"}}'),i=a(74848),s=a(28453),o=a(50773),l=a(57250);let t={},c="MapboxOverlay",d={},p=[{value:"Example",id:"example",level:2},{value:"Constructor",id:"constructor",level:2},{value:"Methods",id:"methods",level:2},{value:"setProps",id:"setprops",level:5},{value:"pickObject",id:"pickobject",level:5},{value:"pickObjects",id:"pickobjects",level:5},{value:"pickMultipleObjects",id:"pickmultipleobjects",level:5},{value:"finalize",id:"finalize",level:5},{value:"getCanvas",id:"getcanvas",level:5},{value:"Remarks",id:"remarks",level:2},{value:"Antialiasing",id:"antialiasing",level:3},{value:"Multi-view usage",id:"multi-view-usage",level:3}];function h(e){let n={a:"a",code:"code",h1:"h1",h2:"h2",h3:"h3",h5:"h5",header:"header",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,s.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(n.header,{children:(0,i.jsx)(n.h1,{id:"mapboxoverlay",children:"MapboxOverlay"})}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.code,{children:"MapboxOverlay"})," is an implementation of ",(0,i.jsx)(n.a,{href:"https://www.npmjs.com/package/mapbox-gl",children:"Mapbox GL JS"}),"'s ",(0,i.jsx)(n.a,{href:"https://docs.mapbox.com/mapbox-gl-js/api/markers/#icontrol",children:"IControl"})," API. When adding a ",(0,i.jsx)(n.code,{children:"MapboxOverlay"})," control to an mapbox map, deck.gl layers are rendered in synchronization with the base map layers. This control supports both ",(0,i.jsx)(n.a,{href:"/docs/get-started/using-with-map",children:"overlaid and interleaved"})," rendering modes."]}),"\n",(0,i.jsx)(n.h2,{id:"example",children:"Example"}),"\n","\n",(0,i.jsxs)(o.A,{groupId:"language",children:[(0,i.jsx)(l.A,{value:"ts",label:"TypeScript",children:(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-ts",children:"import {MapboxOverlay} from '@deck.gl/mapbox';\nimport {ScatterplotLayer} from '@deck.gl/layers';\nimport mapboxgl from 'mapbox-gl';\nimport 'mapbox-gl/dist/mapbox-gl.css';\n\nconst map = new mapboxgl.Map({\n container: 'map',\n style: 'mapbox://styles/mapbox/light-v9',\n accessToken: '<mapbox_access_token>',\n center: [0.45, 51.47],\n zoom: 11\n});\n\nmap.once('load', () => {\n const deckOverlay = new MapboxOverlay({\n interleaved: true,\n layers: [\n new ScatterplotLayer({\n id: 'deckgl-circle',\n data: [\n {position: [0.45, 51.47]}\n ],\n getPosition: d => d.position,\n getFillColor: [255, 0, 0, 100],\n getRadius: 1000,\n beforeId: 'waterway-label' // In interleaved mode render the layer under map labels. Replace with `slot: 'bottom'` if using Mapbox v3 Standard Style.\n })\n ]\n });\n\n map.addControl(deckOverlay);\n});\n"})})}),(0,i.jsxs)(l.A,{value:"react",label:"React",children:[(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-tsx",children:"import React from 'react';\nimport {Map, useControl} from 'react-map-gl/mapbox';\nimport {MapboxOverlay} from '@deck.gl/mapbox';\nimport {DeckProps} from '@deck.gl/core';\nimport {ScatterplotLayer} from '@deck.gl/layers';
1\nimport 'mapbox-gl/dist/mapbox-gl.css';\n\nfunction DeckGLOverlay(props: DeckProps) {\n const overlay = useControl<MapboxOverlay>(() => new MapboxOverlay(props));\n overlay.setProps(props);\n return null;\n}\n\nfunction App() {\n const layers: [\n new ScatterplotLayer({\n id: 'deckgl-circle',\n data: [\n {position: [0.45, 51.47]}\n ],\n getPosition: d => d.position,\n getFillColor: [255, 0, 0, 100],\n getRadius: 1000,\n beforeId: 'waterway-label' // In interleaved mode render the layer under map labels. Replace with `slot: 'bottom'` if using Mapbox v3 Standard Style.\n })\n ];\n\n return (\n <Map\n initialViewState={{\n longitude: 0.45,\n latitude: 51.47,\n zoom: 11\n }}\n mapStyle=\"mapbox://styles/mapbox/light-v9\"\n mapboxAccessToken=\"<mapbox_access_token>\"\n >\n <DeckGLOverlay layers={layers} interleaved />\n </Map>\n );\n}\n"})}),(0,i.jsxs)(n.p,{children:["See react-map-gl's ",(0,i.jsx)(n.a,{href:"https://visgl.github.io/react-map-gl/docs/api-reference/use-control",children:"useControl"})," hook."]})]})]}),"\n",(0,i.jsx)(n.h2,{id:"constructor",children:"Constructor"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-ts",children:"import {MapboxOverlay} from '@deck.gl/mapbox';\nimport type {MapboxOverlayProps} from '@deck.gl/mapbox';\n\nnew MapboxOverlay(props: MapboxOverlayProps);\n"})}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.code,{children:"MapboxOverlay"})," accepts the same props as the ",(0,i.jsx)(n.a,{href:"/docs/api-reference/core/deck",children:"Deck"})," class, with the following exceptions:"]}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"views"})," - multi-view support is limited. There is only one ",(0,i.jsx)(n.code,{children:"MapView"})," that can synchronize with the base map. See the ",(0,i.jsx)(n.a,{href:"#multi-view-usage",children:"using with multi-views"})," section for details."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"parent"})," / ",(0,i.jsx)(n.code,{children:"canvas"})," / ",(0,i.jsx)(n.code,{children:"device"})," - context creation is managed internally."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"viewState"})," / ",(0,i.jsx)(n.code,{children:"initialViewState"})," - camera state is managed internally."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"controller"})," - always disabled (to use Mapbox's interaction handlers)."]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"useDevicePixels"})," - ignored in interleaved mode, where the base map owns the WebGL context and the canvas drawing buffer size. To control pixel ratio in interleaved mode, use MapLibre's ",(0,i.jsx)(n.a,{href:"https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/MapOptions/#pixelratio",children:(0,i.jsx)(n.code,{children:"pixelRatio"})})," constructor option on the Map instance. Mapbox GL JS does not expose an equivalent option."]}),"\n"]}),"\n",(0,i.jsx)(n.p,{children:"The constructor additionally accepts the following options:"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"interleaved"})," (boolean) - If ",(0,i.jsx)(n.code,{children:"false"}),", a dedicated deck.gl canvas is added on top of the base map. If ",(0,i.jsx)(n.code,{children:"true"}),", deck.gl layers are inserted into mapbox-gl's layer stack, and share the same ",(0,i.jsx)(n.code,{children:"WebGL2RenderingContext"})," as the base map. Default is ",(0,i.jsx)(n.code,{children:"false"}),". Note that interleaving with basemaps such as mapbox-gl-js v1 that only support WebGL 1 is not supported, see ",(0,i.jsx)(n.a,{href:"./overview#interleaved-renderer-compatibility",children:"compatibility"}),"."]}),"\n"]}),"\n",(0,i.jsxs)(n.p,{children:["When using ",(0,i.jsx)(n.code,{children:"interleaved: true"}),", deck.gl layers are grouped by their ",(0,i.jsx)(n.code,{children:"beforeId"})," or ",(0,i.jsx)(n.code,{children:"slot"})," prop and rendered in batches. You may control the ordering of layers in the Mapbox/MapLibre stack by optionally adding a ",(0,i.jsx)(n.code,{children:"beforeId"})," prop to a layer. If multiple deck.gl layers have the same ",(0,i.jsx)(n.code,{children:"beforeId"}),", they are rendered together in the order that is passed into the ",(0,i.jsx)(n.code,{children:"layers"})," array, enabling cross-layer extension handling (e.g. MaskExtension, CollisionFilterExtension). If used with Mapbox v3 Standard Style, supply a ",(0,i.jsx)(n.a,{href:"https://docs.mapbox.com/mapbox-gl-js/guides/migrate/#layer-slots",children:"slot"})," prop to layers instead."]}),"\n",(0,i.jsxs)(n.p,{children:["Note that extensions which require layers to share a rendering context (such as MaskExtension and CollisionFilterExtension) only w
1ork between layers within the same group. Ensure that layers using these extensions share the same ",(0,i.jsx)(n.code,{children:"beforeId"})," or ",(0,i.jsx)(n.code,{children:"slot"})," value."]}),"\n",(0,i.jsx)(n.h2,{id:"methods",children:"Methods"}),"\n",(0,i.jsx)(n.h5,{id:"setprops",children:"setProps"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-ts",children:"const overlay = new MapboxOverlay({\n interleaved: true,\n layers: []\n});\n\nmap.addControl(overlay);\n\n// Update layers\noverlay.setProps({\n layers: [new ScatterplotLayer({...})]\n})\n"})}),"\n",(0,i.jsxs)(n.p,{children:["Updates (partial) props of the underlying ",(0,i.jsx)(n.code,{children:"Deck"})," instance. See ",(0,i.jsx)(n.a,{href:"/docs/api-reference/core/deck#setprops",children:"Deck.setProps"}),"."]}),"\n",(0,i.jsx)(n.h5,{id:"pickobject",children:"pickObject"}),"\n",(0,i.jsxs)(n.p,{children:["See ",(0,i.jsx)(n.a,{href:"/docs/api-reference/core/deck#pickobject",children:"Deck.pickObject"}),"."]}),"\n",(0,i.jsx)(n.h5,{id:"pickobjects",children:"pickObjects"}),"\n",(0,i.jsxs)(n.p,{children:["See ",(0,i.jsx)(n.a,{href:"/docs/api-reference/core/deck#pickobjects",children:"Deck.pickObjects"}),"."]}),"\n",(0,i.jsx)(n.h5,{id:"pickmultipleobjects",children:"pickMultipleObjects"}),"\n",(0,i.jsxs)(n.p,{children:["See ",(0,i.jsx)(n.a,{href:"/docs/api-reference/core/deck#pickmultipleobjects",children:"Deck.pickMultipleObjects"}),"."]}),"\n",(0,i.jsx)(n.h5,{id:"finalize",children:"finalize"}),"\n",(0,i.jsx)(n.p,{children:"Removes the control and deletes all resources."}),"\n",(0,i.jsx)(n.h5,{id:"getcanvas",children:"getCanvas"}),"\n",(0,i.jsxs)(n.p,{children:["See ",(0,i.jsx)(n.a,{href:"/docs/api-reference/core/deck#getcanvas",children:"Deck.getCanvas"}),". When using ",(0,i.jsx)(n.code,{children:"interleaved: true"}),", returns the base map's ",(0,i.jsx)(n.code,{children:"canvas"}),"."]}),"\n",(0,i.jsx)(n.h2,{id:"remarks",children:"Remarks"}),"\n",(0,i.jsx)(n.h3,{id:"antialiasing",children:"Antialiasing"}),"\n",(0,i.jsxs)(n.p,{children:["Base maps create their WebGL context with ",(0,i.jsx)(n.code,{children:"antialias: false"}),", so in interleaved mode deck.gl layers receive no multisampling. Layers that rely on it \u2014 including ",(0,i.jsx)(n.a,{href:"/docs/api-reference/layers/path-layer",children:"PathLayer"}),", ",(0,i.jsx)(n.a,{href:"/docs/api-reference/layers/line-layer",children:"LineLayer"}),", ",(0,i.jsx)(n.a,{href:"/docs/api-reference/layers/arc-layer",children:"ArcLayer"}),", and ",(0,i.jsx)(n.a,{href:"/docs/api-reference/layers/point-cloud-layer",children:"PointCloudLayer"})," \u2014 will look aliased against the base map. Set ",(0,i.jsx)(n.code,{children:"antialiasing: true"})," on those layers, or enable MSAA on the base map itself."]}),"\n",(0,i.jsx)(n.h3,{id:"multi-view-usage",children:"Multi-view usage"}),"\n",(0,i.jsxs)(n.p,{children:["When using ",(0,i.jsx)(n.code,{children:"MapboxOverlay"})," with multiple views passed to the ",(0,i.jsx)(n.code,{children:"views"})," prop, only one of the views can match the base map and receive interaction."]}),"\n",(0,i.jsxs)(n.p,{children:["With that said, it is still possible to take advantage of deck's multi-view system and render a mapbox base map onto any one ",(0,i.jsx)(n.code,{children:"MapView"})," of your choice by setting the ",(0,i.jsx)(n.code,{children:"views"})," array and a ",(0,i.jsx)(n.code,{children:"layerFilter"})," callback."]}),"\n",(0,i.jsx)(n.p,{children:(0,i.jsx)(n.strong,{children:"View ID Conventions:"})}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"MapboxOverlay"})," internally uses a ",(0,i.jsx)(n.code,{children:"MapView"})," with the id ",(0,i.jsx)(n.code,{children:'"mapbox"'})," to synchronize with the base map's camera."]}),"\n",(0,i.jsxs)(n.li,{children:["You can reference this view id in your ",(0,i.jsx)(n.code,{children:"layerFilter"})," to control which layers render on the main map."]}),"\n",(0,i.jsxs)(n.li,{children:["When providing custom views, you do ",(0,i.jsx)(n.strong,{children:"not"})," need to explicitly include a view with id ",(0,i.jsx)(n.code,{children:'"mapbox"'})," - it will be automatically injected if not present."]}),"\n",(0,i.jsxs)(n.li,{children:["If you want to customize the mapbox-synchronized view (e.g., to control draw order with other custom views), you can explicitly define a ",(0,i.jsx)(n.code,{children:"MapView({id: 'mapbox'})"})," in your views array."]}),"\n"]}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-ts",children:"import {MapboxOverlay} from '@deck.gl/mapbox';
1\nimport {Deck, MapView, OrthographicView} from '@deck.gl/core';\nimport {ScatterplotLayer} from '@deck.gl/layers';\n\nconst map = new mapboxgl.Map({...});\n\nconst overlay = new MapboxOverlay({\n views: [\n // This view will be synchronized with the base map\n new MapView({id: 'mapbox'}),\n // This view will not be interactive\n new OrthographicView({id: 'widget'})\n ],\n layerFilter: ({layer, viewport}) => {\n const shouldDrawInWidget = layer.id.startsWith('widget');\n if (viewport.id === 'widget') return shouldDrawInWidget;\n return !shouldDrawInWidget;\n },\n layers: [\n new ScatterplotLayer({\n id: 'my-scatterplot',\n data: [\n {position: [-74.5, 40], size: 100}\n ],\n getPosition: d => d.position,\n getRadius: d => d.size,\n getFillColor: [255, 0, 0]\n }),\n new ScatterplotLayer({\n id: 'widget-scatterplot',\n data: [\n {position: [0, 0], size: 100}\n ],\n getPosition: d => d.position,\n getRadius: d => d.size,\n getFillColor: [255, 0, 0]\n })\n ]\n});\n\nmap.addControl(overlay);\n"})})]})}function x(e={}){let{wrapper:n}={...(0,s.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(h,{...e})}):h(e)}}}]); 2//# sourceMappingURL=57500931.37afee7c.js.map
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.