TileManager zoom hysteresis bypasses maxZoom constraint

[jarda-manana]

Description

When the map's zoom level exceeds a tile layer's configured maxZoom, the zoom hysteresis logic in TileManager.update() can override the clamped tileZoom value, causing tile requests at zoom levels beyond maxZoom.

Steps to reproduce

1. Create a BitmapTileLayer with a tile source that has maxZoom = 7
2. Set the map position to zoom level 8 or higher
3. Observe that tile requests are made at zoom 8 instead of being clamped to 7

Root cause

In TileManager.update(), mPrevZoomlevel is initialized from the unclamped pos.zoomLevel:

  if (mNewTiles == null || mNewTiles.tiles.length == 0) {
      mPrevZoomlevel = pos.zoomLevel;  // unclamped — can exceed mMaxZoom
      init();
  }

  int tileZoom = clamp(pos.zoomLevel, mMinZoom, mMaxZoom);  // correctly clamped

  // Hysteresis logic:
  int zoomDiff = tileZoom - mPrevZoomlevel;  // e.g., 7 - 8 = -1
  if (zoomDiff == -1) {
      if (scaleDiv > mLevelDownThreshold) {
          tileZoom = mPrevZoomlevel;  // reverts to 8, bypassing maxZoom
      }
  }
  mPrevZoomlevel = tileZoom;  // persists the unclamped value

The hysteresis interprets the clamped-vs-unclamped difference as a "zoom out" and holds the previous (unclamped) zoom level. This persists on subsequent updates because mPrevZoomlevel remains above mMaxZoom.

Suggested fix

Clamp mPrevZoomlevel during initialization:

  if (mNewTiles == null || mNewTiles.tiles.length == 0) {
      mPrevZoomlevel = clamp(pos.zoomLevel, mMinZoom, mMaxZoom);
      init();
  }

Or apply the clamp after the hysteresis adjustment:

  // after the threshold logic block:
  tileZoom = clamp(tileZoom, mMinZoom, mMaxZoom);
  mPrevZoomlevel = tileZoom;

Impact

Any BitmapTileLayer (or other tile layer) with a maxZoom lower than the map's current zoom level will request tiles beyond its configured maximum. This causes unnecessary HTTP requests to non-existent tile endpoints and potential rendering issues.

[devemux86]

@jarda-manana Thanks for the report.

How can we test and reproduce it?

Set in DefaultSources.OPENSTREETMAP the zoomMax to 8,
then zoom the map beyond the level 8, the requested tiles stop correctly at level 8.

[jarda-manana]

Thanks for looking into this!

The issue only manifests when the BitmapTileLayer is an overlay on a base map with higher maxZoom — not when it's the sole/primary layer. In my case: vector base map (maxZoom 17) + rain radar BitmapTileLayer overlay
(maxZoom 7).

To reproduce:

1. Create a map with a base layer supporting high zoom (e.g., default vector map)
2. Add a BitmapTileLayer overlay with low maxZoom (e.g., 7)
3. Zoom to exactly maxZoom + 1 (zoom 8)
4. While at zoom 8, create/add the overlay layer — this triggers the init path where mPrevZoomlevel = pos.zoomLevel (8, unclamped)

The hysteresis then kicks in: zoomDiff = 7 - 8 = -1, scaleDiv > mLevelDownThreshold, so tileZoom reverts to 8. This persists on every subsequent update at zoom 8.

The -1 difference is key — at zoom 9+ the difference is larger, hysteresis is skipped, and it works correctly.

[devemux86]

@jarda-manana See #1287, does it improve the situation?

[jarda-manana]

Looks good to me 👍
Thank you!