diff options
Diffstat (limited to 'platform/darwin/src/MGLTileSource.h')
-rw-r--r-- | platform/darwin/src/MGLTileSource.h | 123 |
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 /** |