TileLayer: add zoomOffset prop (visgl#5896)

docs/api-reference/geo-layers/tile-layer.md

@@ -84,6 +84,8 @@ When the `TileLayer` is used with a geospatial view such as the [MapView](/docs/
 
 When the `TileLayer` is used used with a non-geospatial view such as the [OrthographicView](/docs/api-reference/core/orthographic-view.md) or the [OrbitView](/docs/api-reference/core/orbit-view.md), `x` and `y` increment from the world origin, and each tile's width and height match that defined by the `tileSize` prop. For example, the tile `x: 0, y: 0` occupies the square between `[0, 0]` and `[tileSize, tileSize]`.
 
+If you need to offset the `z` level at which the tiles are fetched in order to fetch tiles at a higher resolution in order to produce a "crisper" picture, there is a `zoomOffset` prop.
+
 
 ## Properties
 
@@ -138,10 +140,17 @@ if (signal.aborted) {
 
 The pixel dimension of the tiles, usually a power of 2.
 
-The tile size represents the target pixel width and height of each tile when rendered. Smaller tile sizes display the content at higher resolution, while the layer needs to load more tiles to fill the same viewport.
+For geospatial viewports, tile size represents the target pixel width and height of each tile when rendered. Smaller tile sizes display the content at higher resolution, while the layer needs to load more tiles to fill the same viewport.
+
+For non-geospatial viewports, the tile size should correspond to the true pixel size of the tiles.
 
 - Default: `512`
 
+##### `zoomOffset` (Number, optional)
+
+This offset changes the zoom level at which the tiles are fetched.  Needs to be an integer.
+
+- Default: `0`
 
 ##### `maxZoom` (Number|Null, optional)
 

docs/upgrade-guide.md

@@ -24,6 +24,7 @@ The module entry point is now only lightly transpiled for the most commonly used
 - `CartoBQTilerLayer` will be deprecated in 8.6. Use `CartoLayer` instead with `type` to `MAP_TYPES.TILESET`.
 - `CartoSQLLayer` will be deprecated in 8.6. Use `CartoLayer` instead with `type` to `MAP_TYPES.QUERY`.
 - `GeoJsonLayer`'s `getRadius` props is deprecated, replaced by `getPointRadius`.
+- It is recommended to use `zoomOffset` in the `TileLayer` when trying to affect the `zoom` resolution at which tiles are fetched.
 
 ### onError Callback
 

examples/website/map-tile/app.js

@@ -42,8 +42,8 @@ export default function App({showBorder = false, onTilesLoad = null}) {
     // https://wiki.openstreetmap.org/wiki/Zoom_levels
     minZoom: 0,
     maxZoom: 19,
-    tileSize: 512 / devicePixelRatio,
-
+    tileSize: 256,
+    zoomOffset: devicePixelRatio === 1 ? -1 : 0,
     renderSubLayers: props => {
       const {
         bbox: {west, south, east, north}

modules/geo-layers/src/tile-layer/tile-layer.js

@@ -23,7 +23,8 @@ const defaultProps = {
   maxCacheByteSize: null,
   refinementStrategy: STRATEGY_DEFAULT,
   zRange: null,
-  maxRequests: 6
+  maxRequests: 6,
+  zoomOffset: 0
 };
 
 export default class TileLayer extends CompositeLayer {
@@ -89,7 +90,8 @@ export default class TileLayer extends CompositeLayer {
       maxCacheByteSize,
       refinementStrategy,
       extent,
-      maxRequests
+      maxRequests,
+      zoomOffset
     } = props;
 
     return {
@@ -100,7 +102,8 @@ export default class TileLayer extends CompositeLayer {
       tileSize,
       refinementStrategy,
       extent,
-      maxRequests
+      maxRequests,
+      zoomOffset
     };
   }
 

modules/geo-layers/src/tile-layer/tileset-2d.js

@@ -159,7 +159,7 @@ export default class Tileset2D {
 
   // Returns array of {x, y, z}
   getTileIndices({viewport, maxZoom, minZoom, zRange, modelMatrix, modelMatrixInverse}) {
-    const {tileSize, extent} = this.opts;
+    const {tileSize, extent, zoomOffset} = this.opts;
     return getTileIndices({
       viewport,
       maxZoom,
@@ -168,7 +168,8 @@ export default class Tileset2D {
       tileSize,
       extent,
       modelMatrix,
-      modelMatrixInverse
+      modelMatrixInverse,
+      zoomOffset
     });
   }
 

modules/geo-layers/src/tile-layer/utils.js

@@ -177,11 +177,12 @@ export function getTileIndices({
   extent,
   tileSize = TILE_SIZE,
   modelMatrix,
-  modelMatrixInverse
+  modelMatrixInverse,
+  zoomOffset = 0
 }) {
   let z = viewport.isGeospatial
-    ? Math.round(viewport.zoom + Math.log2(TILE_SIZE / tileSize))
-    : Math.ceil(viewport.zoom);
+    ? Math.round(viewport.zoom + Math.log2(TILE_SIZE / tileSize)) + zoomOffset
+    : Math.ceil(viewport.zoom) + zoomOffset;
   if (Number.isFinite(minZoom) && z < minZoom) {
     if (!extent) {
       return [];

test/modules/geo-layers/tile-layer/utils.spec.js

@@ -131,6 +131,32 @@ const TEST_CASES = [
     }),
     output: ['2,2,4', '2,3,4', '3,2,4', '3,3,4']
   },
+  {
+    title: 'non-geospatial with zoom offset',
+    viewport: new OrthographicView().makeViewport({
+      width: 800,
+      height: 400,
+      viewState: {
+        target: [100, 100],
+        zoom: 4
+      }
+    }),
+    zoomOffset: 1,
+    output: [
+      '4,5,5',
+      '4,6,5',
+      '4,7,5',
+      '5,5,5',
+      '5,6,5',
+      '5,7,5',
+      '6,5,5',
+      '6,6,5',
+      '6,7,5',
+      '7,5,5',
+      '7,6,5',
+      '7,7,5'
+    ]
+  },
   {
     title: 'non-geospatial with tile size',
     viewport: new OrthographicView().makeViewport({
@@ -295,7 +321,8 @@ test('getTileIndices', t => {
       tileSize,
       modelMatrix,
       extent,
-      modelMatrixInverse
+      modelMatrixInverse,
+      zoomOffset
     } = testCase;
     const result = getTileIndices({
       viewport,
@@ -305,7 +332,8 @@ test('getTileIndices', t => {
       tileSize,
       modelMatrix,
       modelMatrixInverse,
-      extent
+      extent,
+      zoomOffset
     });
     t.deepEqual(getTileIds(result), testCase.output, testCase.title);
   }