Deprecate MapboxLayer in favor of MapboxOverlay

[chrisgervang]

MapboxOverlay supports the same features as MapboxLayer and is more aligned with our other basemap integrations. Migration should be straightforward.

// deck.gl v9
import {DeckOverlay} from '@deck.gl/mapbox'
map.addControl(new DeckOverlay({
  interleaved: true,
  layers: [new ArcLayer({...})]
}))
// deck.gl v8
import {MapboxLayer} from '@deck.gl/mapbox'
map.addLayer(new MapboxLayer({type: ArcLayer, ...}))

Examples of the migration:

• https://github.com/visgl/deck.gl/pull/8558
• react https://github.com/visgl/deck.gl/pull/8555
• pure-js https://github.com/visgl/deck.gl/pull/8558/files/a83529f3bc26700d7a71f66a4672dbc9f9737c4d

[birkskyum]

@harelm TIL - the deckgl data layers go in through the addControl, so it's used for more than html elements. I tried this overlay in a local MapLibre app with large deckgl IconLayers where I drag the viewport around really fast, and setting the interleaved: true gave me min. 110fps (🎉), where interleaved: false was min. 80fps (similar to having 2 canvas and not using the Overlay class) . For some reason I expected interleaved mode to be more heavy, but I'm happy to learn it's the faster of them as it's the nicer option for virtually all cases (no frame lag etc.).

[HarelM]

Well, IControl is simply an interface that has onAdd and onRemove so you can do a lot of things with it that are not HTML I guess. :-) I still don't like the fact that it is called Mapbox when I believe we are a lot more cooperative to the deck.gl and react community, but that might just be me :-)

[birkskyum]

@HarelM , I think everyone involved are well aware, and supportive of, the need for a separate api with the ongoing divergence.

[HarelM]

Oh, I see, that's great to hear! Keep up the good work!

[rbrundritt]

I figured out how to get v9 to work. I'll update the samples. Here are the main changes:

1. Replace the DeckGLLayer class with a new class that can be added as a control (code below). I could have modified the DeckGLLayer class, but that only handles a single layer, while the overlay can manage multiple layers and becomes a single point of entry for deck.gl into Azure Maps.
2. Create an instance of this class using the options of an deckgl overlay (layers is an array of layers in the options). Add the overlay as a control to the map.

Here are some code blocks:

class DeckGLOverlay {
    constructor(options) {
        this.id = options.id;

        // Create an instance of deck.gl MapboxOverlay what is compatible with Azure Maps
        // https://deck.gl/docs/api-reference/mapbox/mapbox-overlay
        this._mbOverlay = new deck.MapboxOverlay(options);
    }

    onAdd(map, options) {
        this.map = map;
        return this._mbOverlay.onAdd(map["map"]);
    }

    onRemove() {
        this._mbOverlay.onRemove();
    }

    getCanvas() {
        this._mbOverlay.getCanvas();
    }

    getId() {
        return this.id;
    }

    pickObject(params) {
        return this._mbOverlay.pickObject(params);
    }

    pickMultipleObjects(params) {
        return this._mbOverlay.pickMultipleObjects(params);
    }

    pickObjects(params) {
        return this._mbOverlay.pickObjects();
    }

    setProps(props) {
        this._mbOverlay.setProps(props);
    }

    finalize() {
        this._mbOverlay.finalize();
    }
}

 map.controls.add(new DeckGLOverlay({
     layers: [
         new deck.ArcLayer({
             id: "arc",
             data: calculateArcs(features),
             getSourcePosition: (d) => d.source,
             getTargetPosition: (d) => d.target,
             getSourceColor: [255, 0, 0],
             getTargetColor: [0, 255, 0],
             getWidth: 2
         })
     ]
 }));

[dimi4e]

So if I understand correctly, in this version of the API I can no longer manage order of rendering layers using beforeId prop ?

[chrisgervang]

That's still supported by using new DeckOverlay({...deckProps, layers, interleaved: true}). The overlay will inspect beforeId to draw before Mapbox/Maplibre layers.