Merge branch 'release-ios-v3.4.0' into 1ec5-release-ios-v3.4.0-beta.7

1 files changed, 121 insertions, 2 deletions

diff --git a/platform/darwin/src/MGLTileSource.h b/platform/darwin/src/MGLTileSource.h
index 7e1a8206a3..99d23f4add 100644
--- a/platform/darwin/src/MGLTileSource.h
+++ b/platform/darwin/src/MGLTileSource.h
@@ -20,6 +20,10 @@ typedef NSString *MGLTileSourceOption NS_STRING_ENUM;
  The value should be between 0 and 22, inclusive, and less than
  `MGLTileSourceOptionMaximumZoomLevel`, if specified. The default value for this
  option is 0.
+
+ This option corresponds to the `minzoom` key in the
+ <a href="https://github.com/mapbox/tilejson-spec/tree/master/2.1.0">TileJSON</a>
+ specification.
  */
 extern MGL_EXPORT const MGLTileSourceOption MGLTileSourceOptionMinimumZoomLevel;
 
@@ -30,6 +34,10 @@ extern MGL_EXPORT const MGLTileSourceOption MGLTileSourceOptionMinimumZoomLevel;
  The value should be between 0 and 22, inclusive, and less than
  `MGLTileSourceOptionMinimumZoomLevel`, if specified. The default value for this
  option is 22.
+
+ This option corresponds to the `maxzoom` key in the
+ <a href="https://github.com/mapbox/tilejson-spec/tree/master/2.1.0">TileJSON</a>
+ specification.
  */
 extern MGL_EXPORT const MGLTileSourceOption MGLTileSourceOptionMaximumZoomLevel;
 
@@ -42,6 +50,10 @@ extern MGL_EXPORT const MGLTileSourceOption MGLTileSourceOptionMaximumZoomLevel;
  By default, no attribution statements are displayed. If the
  `MGLTileSourceOptionAttributionInfos` option is specified, this option is
  ignored.
+
+ This option corresponds to the `attribution` key in the
+ <a href="https://github.com/mapbox/tilejson-spec/tree/master/2.1.0">TileJSON</a>
+ specification.
  */
 extern MGL_EXPORT const MGLTileSourceOption MGLTileSourceOptionAttributionHTMLString;
 
@@ -61,6 +73,10 @@ extern MGL_EXPORT const MGLTileSourceOption MGLTileSourceOptionAttributionInfos;
  By default, no attribution statements are displayed. If the
  `MGLTileSourceOptionAttributionInfos` option is specified, this option is
  ignored.
+
+ This option corresponds to the `attribution` key in the
+ <a href="https://github.com/mapbox/tilejson-spec/tree/master/2.1.0">TileJSON</a>
+ specification.
  */
 extern MGL_EXPORT const MGLTileSourceOption MGLTileSourceOptionAttributionHTMLString;
 
@@ -80,6 +96,10 @@ extern MGL_EXPORT const MGLTileSourceOption MGLTileSourceOptionAttributionInfos;
  the constants described in `MGLTileCoordinateSystem`.
  
  The default value for this option is `MGLTileCoordinateSystemXYZ`.
+
+ This option corresponds to the `scheme` key in the
+ <a href="https://github.com/mapbox/tilejson-spec/tree/master/2.1.0">TileJSON</a>
+ specification.
  */
 extern MGL_EXPORT const MGLTileSourceOption MGLTileSourceOptionTileCoordinateSystem;
 
@@ -150,13 +170,101 @@ MGL_EXPORT
 /**
  Returns a tile source initialized an identifier, tile URL templates, and
  options.
-
+ 
  After initializing and configuring the source, add it to a map view’s style
  using the `-[MGLStyle addSource:]` method.
  
+ #### Tile URL templates
+ 
+ Tile URL templates are strings that specify the URLs of the tile images to
+ load. Each template resembles an absolute URL, but with any number of
+ placeholder strings that the source evaluates based on the tile it needs to
+ load. For example:
+ 
+ <ul>
+ <li><code>http://www.example.com/tiles/{z}/{x}/{y}.pbf</code> could be
+    evaluated as <code>http://www.example.com/tiles/14/6/9.pbf</code>.</li>
+ <li><code>http://www.example.com/tiles/{z}/{x}/{y}{ratio}.png</code> could be
+    evaluated as <code>http://www.example.com/tiles/14/6/9@2x.png</code>.</li>
+ </ul>
+ 
+ Tile sources support the following placeholder strings in tile URL templates,
+ all of which are optional:
+ 
+ <table>
+ <thead>
+ <tr><th>Placeholder string</th><th>Description</th></tr>
+ </thead>
+ <tbody>
+ <tr>
+     <td><code>{x}</code></td>
+     <td>The index of the tile along the map’s x axis according to Spherical
+        Mercator projection. If the value is 0, the tile’s left edge corresponds
+        to the 180th meridian west. If the value is 2<sup><var>z</var></sup>−1,
+        the tile’s right edge corresponds to the 180th meridian east.</td>
+ </tr>
+ <tr>
+     <td><code>{y}</code></td>
+     <td>The index of the tile along the map’s y axis according to Spherical
+        Mercator projection. If the value is 0, the tile’s tile edge corresponds
+        to arctan(sinh(π)), or approximately 85.0511 degrees north. If the value
+        is 2<sup><var>z</var></sup>−1, the tile’s bottom edge corresponds to
+        −arctan(sinh(π)), or approximately 85.0511 degrees south. The y axis is
+        inverted if the <code>options</code> parameter contains
+        <code>MGLTileSourceOptionTileCoordinateSystem</code> with a value of
+        <code>MGLTileCoordinateSystemTMS</code>.</td>
+ </tr>
+ <tr>
+     <td><code>{z}</code></td>
+     <td>The tile’s zoom level. At zoom level 0, each tile covers the entire
+        world map; at zoom level 1, it covers ¼ of the world; at zoom level 2,
+        <sup>1</sup>⁄<sub>16</sub> of the world, and so on. For tiles loaded by
+        a <code>MGLRasterSource</code> object, whether the tile zoom level
+        matches the map’s current zoom level depends on the value of the
+        source’s tile size as specified in the
+        <code>MGLTileSourceOptionTileSize</code> key of the
+        <code>options</code> parameter.</td>
+ </tr>
+ <tr>
+     <td><code>{bbox-epsg-3857}</code></td>
+     <td>The tile’s bounding box, expressed as a comma-separated list of the
+        tile’s western, southern, eastern, and northern extents according to
+        Spherical Mercator (EPSG:3857) projection. The bounding box is typically
+        used with map services conforming to the
+        <a href="http://www.opengeospatial.org/standards/wms">Web Map Service</a>
+        protocol.</td>
+ </tr>
+ <tr>
+     <td><code>{quadkey}</code></td>
+     <td>A quadkey indicating both the tile’s location and its zoom level. The
+        quadkey is typically used with
+        <a href="https://msdn.microsoft.com/en-us/library/bb259689.aspx">Bing Maps</a>.
+     </td>
+ </tr>
+ <tr>
+     <td><code>{ratio}</code></td>
+     <td>A suffix indicating the resolution of the tile image. The suffix is the
+        empty string for standard resolution displays and <code>@2x</code> for
+        Retina displays, including displays for which
+        <code>NSScreen.backingScaleFactor</code> or <code>UIScreen.scale</code>
+        is 3.</td>
+ </tr>
+ <tr>
+     <td><code>{prefix}</code></td>
+     <td>Two hexadecimal digits chosen such that each visible tile has a
+        different prefix. The prefix is typically used for domain sharding.</td>
+ </tr>
+ </tbody>
+ </table>
+ 
+ For more information about the `{x}`, `{y}`, and `{z}` placeholder strings,
+ consult the
+ <a href="https://wiki.openstreetmap.org/wiki/Slippy_map_tilenames">OpenStreetMap Wiki</a>.
+ 
  @param identifier A string that uniquely identifies the source in the style to
     which it is added.
- @param tileURLTemplates An array of tile URL template strings.
+ @param tileURLTemplates An array of tile URL template strings. Only the first
+    string is used; any additional strings are ignored.
  @param options A dictionary containing configuration options. See
     `MGLTileSourceOption` for available keys and values. Pass in `nil` to use
     the default values.
@@ -164,6 +272,17 @@ MGL_EXPORT
  */
 - (instancetype)initWithIdentifier:(NSString *)identifier tileURLTemplates:(NS_ARRAY_OF(NSString *) *)tileURLTemplates options:(nullable NS_DICTIONARY_OF(MGLTileSourceOption, id) *)options;
 
+#pragma mark Accessing a Source’s Content
+
+/**
+ The URL to the TileJSON configuration file that specifies the contents of the
+ source.
+
+ If the receiver was initialized using
+ `-initWithIdentifier:tileURLTemplates:options`, this property is set to `nil`.
+ */
+@property (nonatomic, copy, nullable, readonly) NSURL *configurationURL;
+
 #pragma mark Accessing Attribution Strings
 
 /**