Tile3DLayer: black gaps when switching viewport type (FirstPersonViewport ↔ WebMercatorViewport)

[charlieforward9]

fpv-map-occlusion-bug.mov

Description

When transitioning from FirstPersonViewport back to WebMercatorViewport (crossing a zoom threshold in a unified view system), black/empty gaps appear in the rendered scene. Parts of the 3D tile surface go missing, revealing the black clear color underneath.

Reproduction

Using a custom View subclass that switches getViewportType() between FirstPersonViewport and WebMercatorViewport based on zoom level:

1. Start in map mode (WebMercatorViewport) at zoom ~18 with Google 3D Photorealistic Tiles
2. Scroll in past a zoom threshold to enter FirstPerson mode (FirstPersonViewport)
3. Scroll back out past the threshold to re-enter map mode (WebMercatorViewport)
4. Result: large black gaps appear in the tile rendering — sections of the 3D tileset are missing/culled

The gaps persist for several seconds until the LOD system catches up and re-fetches appropriate tiles for the new viewport.

Expected Behavior

Smooth transition with no visible gaps. Tiles from the previous viewport should remain visible while new tiles load.

Likely Cause

When the viewport type changes from FirstPersonViewport to WebMercatorViewport:

• The frustum culling volume changes dramatically (FP has a narrow forward frustum, map has a top-down wide frustum)
• Tiles that were loaded for the FP frustum get culled immediately
• Replacement tiles for the new map frustum haven't loaded yet
• Result: black gaps during the loading window

The Tile3DLayer / Tileset3D LOD traversal appears to discard tiles that fall outside the new frustum before replacements are available, violating the "best available" refinement strategy.

Environment

• deck.gl 9.2.6
• @loaders.gl/3d-tiles 4.3.4
• Google 3D Photorealistic Tiles (tile.googleapis.com/v1/3dtiles/root.json)
• Custom View with getViewportType() switching between FirstPersonViewport and WebMercatorViewport
• _TerrainExtension enabled, operation: "terrain+draw"

Potential Mitigation

A refinementStrategy: "best-available" approach that retains parent/sibling tiles during viewport type transitions would prevent the gaps. Alternatively, the tile cache could be given a grace period before evicting tiles after a frustum change.

[charlieforward9]

Test: @loaders.gl 4.4.0-alpha.15

Bumped all @loaders.gl/* packages from 4.3.4 to 4.4.0-alpha.15 to test if the newer 3D tiles traversal/caching logic in loaders.gl 4.4 (tracked in visgl/deck.gl#9972) improves the tile retention during viewport type switches.

Packages bumped:

• @loaders.gl/3d-tiles: 4.3.4 → 4.4.0-alpha.15
• @loaders.gl/core: 4.3.4 → 4.4.0-alpha.15
• @loaders.gl/kml: 4.3.4 → 4.4.0-alpha.15
• @loaders.gl/obj: 4.3.4 → 4.4.0-alpha.15
• @loaders.gl/ply: 4.3.4 → 4.4.0-alpha.15

deck.gl unchanged at 9.2.6 — this is a loaders-only bump to isolate whether the tile loading/caching layer is the source of the gaps.

Build status: Clean install, 59 tests pass, no new type errors.

Will report back with runtime observations on whether the black gaps during FirstPersonViewport ↔ WebMercatorViewport transitions are reduced or eliminated with the newer tileset traversal code.

[felixpalmer]

Cool transition (if you ignore the gaps!)

I think it is the same issue as #8685 though, and not to do with FirstPersonViewController, I'm aware of it and would to fix it. I believe you can work around this by setting position: [0, 0, groundHeight] in the viewState