Allow extents to restrict tile ranges requested from the server

The addition of full extent tile ranges also allows us to simplify wrapX
handling for tile layers. By limiting wrapX to true and false as possible
values, we can remove a lot of guessing logic.

externs/olx.js

@@ -4942,11 +4942,10 @@ olx.source.TileWMSOptions.prototype.urls;
 
 
 /**
- * Whether to wrap the world horizontally. The default, `undefined`, is to
- * request out-of-bounds tiles from the server. This works well in e.g.
- * GeoServer. When set to `false`, only one world will be rendered. When set to
- * `true`, tiles will be requested for one world only, but they will be wrapped
- * horizontally to render multiple worlds.
+ * Whether to wrap the world horizontally. When set to `false`, only one world
+ * will be rendered. When `true`, tiles will be requested for one world only,
+ * but they will be wrapped horizontally to render multiple worlds. The default
+ * is `true`.
  * @type {boolean|undefined}
  * @api
  */
@@ -6014,18 +6013,30 @@ olx.tilegrid;
 
 
 /**
- * @typedef {{minZoom: (number|undefined),
+ * @typedef {{extent: (ol.Extent|undefined),
+ *     minZoom: (number|undefined),
  *     origin: (ol.Coordinate|undefined),
  *     origins: (Array.<ol.Coordinate>|undefined),
  *     resolutions: !Array.<number>,
+ *     sizes: (Array.<ol.Size>|undefined),
  *     tileSize: (number|ol.Size|undefined),
- *     tileSizes: (Array.<number|ol.Size>|undefined),
- *     widths: (Array.<number>|undefined)}}
+ *     tileSizes: (Array.<number|ol.Size>|undefined)}}
  * @api
  */
 olx.tilegrid.TileGridOptions;
 
 
+/**
+ * Extent for the tile grid. No tiles outside this extent will be requested by
+ * {@link ol.source.Tile} sources. When no `origin` or `origins` are
+ * configured, the `origin` will be set to the bottom-left corner of the extent.
+ * When no `sizes` are configured, they will be calculated from the extent.
+ * @type {ol.Extent|undefined}
+ * @api
+ */
+olx.tilegrid.TileGridOptions.prototype.extent;
+
+
 /**
  * Minimum zoom. Default is 0.
  * @type {number|undefined}
@@ -6035,7 +6046,7 @@ olx.tilegrid.TileGridOptions.prototype.minZoom;
 
 
 /**
- * Origin. Default is null.
+ * Origin, i.e. the bottom-left corner of the grid. Default is null.
  * @type {ol.Coordinate|undefined}
  * @api stable
  */
@@ -6043,8 +6054,9 @@ olx.tilegrid.TileGridOptions.prototype.origin;
 
 
 /**
- * Origins. If given, the array length should match the length of the
- * `resolutions` array, i.e. each resolution can have a different origin.
+ * Origins, i.e. the bottom-left corners of the grid for each zoom level. If
+ * given, the array length should match the length of the `resolutions` array,
+ * i.e. each resolution can have a different origin.
  * @type {Array.<ol.Coordinate>|undefined}
  * @api stable
  */
@@ -6061,6 +6073,17 @@ olx.tilegrid.TileGridOptions.prototype.origins;
 olx.tilegrid.TileGridOptions.prototype.resolutions;
 
 
+/**
+ * Number of tile rows and columns of the grid for each zoom level. This setting
+ * is only needed for tile coordinate transforms that need to work with origins
+ * other than the bottom-left corner of the grid. No tiles outside this range
+ * will be requested by sources. If an `extent` is also configured, it takes
+ * precedence.
+ * @type {Array.<ol.Size>|undefined}
+ */
+olx.tilegrid.TileGridOptions.prototype.sizes;
+
+
 /**
  * Tile size. Default is `[256, 256]`.
  * @type {number|ol.Size|undefined}
@@ -6079,32 +6102,32 @@ olx.tilegrid.TileGridOptions.prototype.tileSizes;
 
 
 /**
- * Number of tile columns that cover the grid's extent for each zoom level. Only
- * required when used with a source that has `wrapX` set to `true`, and only
- * when the grid's origin differs from the one of the projection's extent. The
- * array length has to match the length of the `resolutions` array, i.e. each
- * resolution will have a matching entry here.
- * @type {Array.<number>|undefined}
- * @api
- */
-olx.tilegrid.TileGridOptions.prototype.widths;
-
-
-/**
- * @typedef {{origin: (ol.Coordinate|undefined),
+ * @typedef {{extent: (ol.Extent|undefined),
+ *     origin: (ol.Coordinate|undefined),
  *     origins: (Array.<ol.Coordinate>|undefined),
  *     resolutions: !Array.<number>,
  *     matrixIds: !Array.<string>,
+ *     sizes: (Array.<ol.Size>|undefined),
  *     tileSize: (number|ol.Size|undefined),
- *     tileSizes: (Array.<number|ol.Size>|undefined),
- *     widths: (Array.<number>|undefined)}}
+ *     tileSizes: (Array.<number|ol.Size>|undefined)}}
  * @api
  */
 olx.tilegrid.WMTSOptions;
 
 
 /**
- * Origin.
+ * Extent for the tile grid. No tiles outside this extent will be requested by
+ * {@link ol.source.WMTS} sources. When no `origin` or `origins` are
+ * configured, the `origin` will be calculated from the extent.
+ * When no `sizes` are configured, they will be calculated from the extent.
+ * @type {ol.Extent|undefined}
+ * @api
+ */
+olx.tilegrid.WMTSOptions.prototype.extent;
+
+
+/**
+ * Origin, i.e. the top-left corner of the grid.
  * @type {ol.Coordinate|undefined}
  * @api
  */
@@ -6112,7 +6135,8 @@ olx.tilegrid.WMTSOptions.prototype.origin;
 
 
 /**
- * Origins. The length of this array needs to match the length of the
+ * Origins, i.e. the top-left corners of the grid for each zoom level. The
+ * length of this array needs to match the length of the
  * `resolutions` array.
  * @type {Array.<ol.Coordinate>|undefined}
  * @api
@@ -6139,6 +6163,18 @@ olx.tilegrid.WMTSOptions.prototype.resolutions;
 olx.tilegrid.WMTSOptions.prototype.matrixIds;
 
 
+/**
+ * Number of tile rows and columns of the grid for each zoom level. The values
+ * here are the `TileMatrixWidth` and `TileMatrixHeight` advertised in the
+ * GetCapabilities response of the WMTS, and define the grid's extent together
+ * with the `origin`. An `extent` can be configured in addition, and will
+ * further limit the extent for which tile requests are made by sources.
+ * @type {Array.<ol.Size>|undefined}
+ * @api
+ */
+olx.tilegrid.WMTSOptions.prototype.sizes;
+
+
 /**
  * Tile size.
  * @type {number|ol.Size|undefined}