fix(mapbox): MapboxOverlay: render deck layers in batches by zbigg · Pull Request #9939 · visgl/deck.gl

zbigg · 2026-01-15T22:28:04Z

Related #8919

Background

Extensions like CollisionExtension/MaskExtension rely heavily on multi-pass rendering and (seem) to require that "all affected" layers using extension to be rendered in one deck._drawLayers call.

This PR experiments with assumptions that bugs related to extensions are largely caused by MapboxOverlay rendering each deck layer in complete separation from other deck layer even if they are in same "batch" (by slot or beforeId).

MapboxOverlay new rendering mode

_renderLayersInGroups: true - means that deck layers in same group are rendered in one "batch"

Change List

MapboxOverlay: render deck layer in batches grouped by beforeId/slot for extension support

zbigg · 2026-01-15T22:33:15Z

Hi,

I'm still working on small, minimal repro of actual bug but seems like it's same issue as #8919. Basically MapboxOverlay is rendering layers (including all pre/post-render effect system) one by one, whereas GoogleMapsOverlay does it in one shot and all extensions based on pre/post-effects are working as expected.

What we have found, if we have following layers:

mask layer
normal layer with MaskExtension to use mask

That if they are rendered in separate deck._drawLayers then mask isn't applied. Seems like same applies to layer with CollisionExtension - all of them need to be called in one deck._drawLayers run otherwise, only first works correctly.

Giving that MapboxOverlay is very fragile, i've hidden this "feature" behind property, so we don't change behavior for all users until solution is proved ok.

Note - i tried to achieve more-or-less same result that is "batching" renders by moving all layers under CompositeLayer, but seems like this is very tricky as

mask layers are identified internally my "root" layer.id
all code related to hover/click in app needed to be adapted

This made me believe that only proper solution is proper rendering management inside MapboxOverlay.

coveralls · 2026-01-15T22:45:01Z

coverage: 91.114% (+0.01%) from 91.1%
when pulling 34947e7 on zbigg/mapboxoverlay-group-rendering
into 6e87cf8 on master.

chrisgervang

Thank you for this. Interesting finding - up until now I assumed there weren't any negative implications of drawing each layer in their own "batch", but it makes sense that these layers coupled by extensions should draw together.

For some background - this module basically creates a MapboxLayer for each deck layer so that they could be re-ordered with beforeId / slot if the user wanted to, but this PR suggests this isn't necessary and now I'm thinking batched drawing may be a better way to go as the default behavior since long standing features rely on it, and this solution preserves the re-ordering feature.

@Pessimistress are there any benefits to having 1:1 mapbox layer:deck layer?

If there aren't, I'm in favor of replacing resolveLayers and MapboxLayer's internals with a grouped implementation entirely.

I'd just ask that we add a remark in the docs about go to correctly group coupled layers, and explain why features like masks won't work across groups.

chrisgervang · 2026-01-16T07:41:33Z

modules/mapbox/src/types.ts

  triggerRepaint(): void;
 }
+
+export type OverlayLayer = Layer<{


Suggested change

export type OverlayLayer = Layer<{

export type MapLayer = Layer<{

Maybe?

Well in this context "Map" is mapbox/libre Map and this type is specifically a deck Layer with specific props.
In this context i think it's more important to disntinguish

Full name would DeckLayerWithOverlayProps - which is too much.

I'll revert to Layer<LayerOverlayProps> which is long but also very good description of actual type.

zbigg · 2026-01-16T08:56:11Z

If there aren't, I'm in favor of replacing resolveLayers and MapboxLayer's internals with a grouped implementation entirely

If you're ok with this then great i can update PR. My context is that i don't understand if that API is good enough for all cases w.r.t extensions so i leaned towards "safe experiment". But after brief research i am still not sure if this is "robust" enough.

I see at least two issues:

1
it works well if all deck layers affected by extensions land in one group - it stops working if with more than one group

2
Mapbox/libre CustomLayerInterface specifies that all pre-rendering should be performed in prerender callback

If the layer needs to render to a texture, it should implement the prerender

I don't know what can possibly go wrong if we what we do - and we do that in render now, but i see signals that fully correct may be even more complex.

That means that full, robust solution would need to look like this:

prerender - layer one for all layer instances, running all "pre-render" passes - no API in deck (?)
groups... - actual screen passes
no idea how/if we do any post-processing and where it should render

I would still propose to make it experiment.

chrisgervang · 2026-01-16T08:42:48Z

modules/mapbox/src/resolve-layer-groups.ts

+  const layers = flatten(newLayers, Boolean) as OverlayLayer[];
+
+  function getGroupId(layer: OverlayLayer): string {
+    return `deck-layer-group:${layer.props.beforeId}:${layer.props.slot}`;


Can slot and beforeId be used simultaneously? I understood it as you'd use one or the other, but I don't have experiencing using slot yet.

Can slot and beforeId be used simultaneously

I don't know. In that sense this is not different than current solution, also not sure how it will behave.

I'll change it to something clearly indicate which layer group comes from manual ordering (beforeId) and which is assigned to slot.

modules/mapbox/src/deck-utils.ts

chrisgervang · 2026-01-16T08:54:34Z

modules/mapbox/src/mapbox-layer-group.ts

+
+  /* Mapbox custom layer methods */
+
+  onAdd(map: Map, gl: WebGL2RenderingContext): void {


What about onRemove, etc?

Also, in reviewing the MapboxLayer I'm seeing some guards to prevent rendering prior to initialization and something about id needing to be immutable - were these intentionally omitted from the grouped version?

MapboxLayer registered itself in deck instance - we don't do that for MapboxLayerGroup, it's not needed.

(notice, we don't add it to "deck.userData")

Groups are just holders of beforeId/slot - they render all layers registered in deck that match this beforeId/slot - again no need to register anywhere/update/remove.

felixpalmer · 2026-01-16T09:39:50Z

docs/api-reference/mapbox/mapbox-overlay.md

+The constructor additionally accepts the following options:

 - `interleaved` (boolean) - If `false`, a dedicated deck.gl canvas is added on top of the base map. If `true`, deck.gl layers are inserted into mapbox-gl's layer stack, and share the same `WebGL2RenderingContext` as the base map. Default is `false`. Note that interleaving with basemaps such as mapbox-gl-js v1 that only support WebGL 1 is not supported, see [compatibility](./overview#interleaved-renderer-compatibility).
+- `_renderLayersInGroups` (boolean, _experimental_) In interleaved mode, render layers in batches to enable cross-layer extension handling. Default is `false`.


I think having this be opt-in is the way to go, we can turn it on by default in the future, but I would only do that as part of a release

zbigg · 2026-01-16T11:10:48Z

@chrisgervang @felixpalmer I've applied suggestions and added unit-tests.

modules/mapbox/src/deck-utils.ts

felixpalmer · 2026-01-16T11:48:11Z

modules/mapbox/src/mapbox-overlay.ts


    map.on('styledata', this._handleStyleChange);
-    resolveLayers(map, this._deck, [], this._props.layers);
+    this._resolveLayers([], this._props.layers);


I see what you're doing, but honestly I would keep the first 2 parameters.

It's asking for trouble when later you have:

private _onRemoveInterleaved(map: Map): void { map.off('styledata', this._handleStyleChange); this._resolveLayers(this._props.layers, []); removeDeckInstance(map); }

what if in the future someone passes in a different map to _onRemoveInterleaved(map)?

charlieforward9 · 2026-01-18T02:54:31Z

I'm thinking batched drawing may be a better way to go as the default behavior since long standing features rely on it

@chrisgervang can you link those long standing features that rely on this for visibility?

chrisgervang · 2026-01-18T17:17:48Z

@charlieforward9 mask and collision extension are mentioned in the description. We don't have a list of extensions that use pre/post render effects but they can be found on the extensions module. Users can also implement custom extensions that need layers drawn together

zbigg changed the title ~~Zbigg/mapboxoverlay group rendering~~ fix(mapbox): MapboxOverlay: render deck layers in batches Jan 15, 2026

zbigg requested review from Pessimistress, chrisgervang, felixpalmer and ibgreen January 15, 2026 22:41

chrisgervang reviewed Jan 16, 2026

View reviewed changes

zbigg marked this pull request as ready for review January 16, 2026 08:45

zbigg requested a review from chrisgervang January 16, 2026 09:00

chrisgervang reviewed Jan 16, 2026

View reviewed changes

zbigg force-pushed the zbigg/mapboxoverlay-group-rendering branch 2 times, most recently from 74fabb3 to b1a5ee3 Compare January 16, 2026 09:36

felixpalmer reviewed Jan 16, 2026

View reviewed changes

zbigg force-pushed the zbigg/mapboxoverlay-group-rendering branch from d3eff73 to 5e6282e Compare January 16, 2026 11:08

zbigg added 14 commits January 16, 2026 12:09

mapbox-overlay batches render for whole layer group

2279c6f

cleanup

64701c6

make it optional

ebc48af

fix ts error

27e1b7b

final fixes

96bacb3

improve layer & group matching

fcc3f32

CR: LayerOverlayProps

f8e4fbd

brief docs

89223d4

fix resolveLayerGroups always move + unneded code

ff863e2

CR / cleanup

1734901

fix setProps

a3fa4f4

improve getLayerGroupId

7db361e

resolve-layer-groups.spec.ts

f355d8a

tests for mapbox-overlay.spec.ts

cf731c1

zbigg force-pushed the zbigg/mapboxoverlay-group-rendering branch from 5e6282e to cf731c1 Compare January 16, 2026 11:09

zbigg requested review from chrisgervang and felixpalmer January 16, 2026 11:10

felixpalmer approved these changes Jan 16, 2026

View reviewed changes

zbigg added 2 commits January 16, 2026 13:00

CR be more safe

38def15

even more safety

34947e7

zbigg force-pushed the zbigg/mapboxoverlay-group-rendering branch from 6f62dd7 to 34947e7 Compare January 16, 2026 12:16

zbigg merged commit 7f96305 into master Jan 16, 2026
5 checks passed

zbigg deleted the zbigg/mapboxoverlay-group-rendering branch January 16, 2026 12:44

felixpalmer pushed a commit that referenced this pull request Jan 16, 2026

fix(mapbox): MapboxOverlay: render deck layers in batches (#9939)

240845d

chrisgervang mentioned this pull request Jan 17, 2026

feat: Update deck.gl to 9.2.6 and enable layer grouping joby-aviation/noodles.gl#273

Merged

4 tasks

zbigg mentioned this pull request Jan 19, 2026

fix(mapbox): In interleaved, batched mode don't render layers twice #9944

Merged

chrisgervang mentioned this pull request Jan 20, 2026

feat(basemap-browser): add batched rendering toggle and multi-view examples #9946

Merged

2 tasks

chrisgervang mentioned this pull request Feb 1, 2026

[Bug] CollisionFilterExtension hides all data in Mapbox interleaved when above BitmapLayer #7864

Closed

7 tasks

chrisgervang added this to the v9.2 patch releases milestone Feb 2, 2026

	export type OverlayLayer = Layer<{
	export type MapLayer = Layer<{


		/* Mapbox custom layer methods */

		onAdd(map: Map, gl: WebGL2RenderingContext): void {

Conversation

zbigg commented Jan 15, 2026

Background

Change List

Uh oh!

zbigg commented Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coveralls commented Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chrisgervang left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chrisgervang Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

zbigg Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

zbigg commented Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

chrisgervang Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

zbigg Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

chrisgervang Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

zbigg Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

felixpalmer Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

zbigg commented Jan 16, 2026

Uh oh!

Uh oh!

felixpalmer Jan 16, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

charlieforward9 commented Jan 18, 2026

Uh oh!

chrisgervang commented Jan 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

zbigg commented Jan 15, 2026 •

edited

Loading

coveralls commented Jan 15, 2026 •

edited

Loading

chrisgervang left a comment •

edited

Loading

zbigg commented Jan 16, 2026 •

edited

Loading

zbigg Jan 16, 2026 •

edited

Loading

zbigg Jan 16, 2026 •

edited

Loading