Merge pull request #3815 from ahocevar/tilegrid-no-surprises

Simplify tilegrid API and internals

externs/olx.js

@@ -4235,7 +4235,8 @@ olx.source.MapQuestOptions.prototype.url;
 
 /**
  * @typedef {{projection: ol.proj.ProjectionLike,
- *     tileGrid: (ol.tilegrid.TileGrid|undefined)}}
+ *     tileGrid: (ol.tilegrid.TileGrid|undefined),
+ *     wrapX: (boolean|undefined)}}
  * @api
  */
 olx.source.TileDebugOptions;
@@ -4257,6 +4258,14 @@ olx.source.TileDebugOptions.prototype.projection;
 olx.source.TileDebugOptions.prototype.tileGrid;
 
 
+/**
+ * Whether to wrap the world horizontally. Default is `true`.
+ * @type {boolean|undefined}
+ * @api
+ */
+olx.source.TileDebugOptions.prototype.wrapX;
+
+
 /**
  * @typedef {{attributions: (Array.<ol.Attribution>|undefined),
  *     crossOrigin: (null|string|undefined),
@@ -6126,8 +6135,7 @@ olx.tilegrid;
 
 
 /**
- * @typedef {{transformTileCoord: (undefined|function(ol.TileCoord, ol.TileCoord=):ol.TileCoord),
- *     extent: (ol.Extent|undefined),
+ * @typedef {{extent: (ol.Extent|undefined),
  *     minZoom: (number|undefined),
  *     origin: (ol.Coordinate|undefined),
  *     origins: (Array.<ol.Coordinate>|undefined),
@@ -6143,7 +6151,7 @@ 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.
+ * configured, the `origin` will be set to the top-left corner of the extent.
  * @type {ol.Extent|undefined}
  * @api
  */
@@ -6160,8 +6168,8 @@ olx.tilegrid.TileGridOptions.prototype.minZoom;
 
 /**
  * The tile grid origin, i.e. where the `x` and `y` axes meet (`[z, 0, 0]`).
- * Tile coordinates increase from left to right and from bottom to top. If not
- * specified, `extent` or `origins` must be provided.
+ * Tile coordinates increase left to right and upwards. If not specified,
+ * `extent` or `origins` must be provided.
  * @type {ol.Coordinate|undefined}
  * @api stable
  */
@@ -6172,8 +6180,8 @@ olx.tilegrid.TileGridOptions.prototype.origin;
  * Tile grid origins, i.e. where the `x` and `y` axes meet (`[z, 0, 0]`), 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. Tile
- * coordinates increase from left to right and from bottom to top. If not
- * specified, `extent` or `origin` must be provided.
+ * coordinates increase left to right and upwards. If not specified, `extent`
+ * or `origin` must be provided.
  * @type {Array.<ol.Coordinate>|undefined}
  * @api stable
  */
@@ -6190,17 +6198,6 @@ 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}
@@ -6234,9 +6231,8 @@ olx.tilegrid.WMTSOptions;
 
 /**
  * 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.
+ * {@link ol.source.Tile} sources. When no `origin` or `origins` are
+ * configured, the `origin` will be set to the top-left corner of the extent.
  * @type {ol.Extent|undefined}
  * @api
  */
@@ -6244,19 +6240,23 @@ olx.tilegrid.WMTSOptions.prototype.extent;
 
 
 /**
- * Origin, i.e. the top-left corner of the grid.
+ * The tile grid origin, i.e. where the `x` and `y` axes meet (`[z, 0, 0]`).
+ * Tile coordinates increase left to right and upwards. If not specified,
+ * `extent` or `origins` must be provided.
  * @type {ol.Coordinate|undefined}
- * @api
+ * @api stable
  */
 olx.tilegrid.WMTSOptions.prototype.origin;
 
 
 /**
- * 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.
+ * Tile grid origins, i.e. where the `x` and `y` axes meet (`[z, 0, 0]`), 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. Tile
+ * coordinates increase left to right and upwards. If not specified, `extent` or
+ * `origin` must be provided.
  * @type {Array.<ol.Coordinate>|undefined}
- * @api
+ * @api stable
  */
 olx.tilegrid.WMTSOptions.prototype.origins;
 
@@ -6285,7 +6285,10 @@ olx.tilegrid.WMTSOptions.prototype.matrixIds;
  * 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.
+ * further limit the extent for which tile requests are made by sources. Note
+ * that when the top-left corner of the `extent` is used as `origin` or
+ * `origins`, then the `y` value must be negative because OpenLayers tile
+ * coordinates increase upwards.
  * @type {Array.<ol.Size>|undefined}
  * @api
  */
@@ -6368,21 +6371,6 @@ olx.tilegrid.XYZOptions.prototype.minZoom;
 olx.tilegrid.XYZOptions.prototype.tileSize;
 
 
-/**
- * @typedef {{resolutions: !Array.<number>}}
- * @api
- */
-olx.tilegrid.ZoomifyOptions;
-
-
-/**
- * Resolutions.
- * @type {!Array.<number>}
- * @api
- */
-olx.tilegrid.ZoomifyOptions.prototype.resolutions;
-
-
 /**
  * Namespace.
  * @type {Object}