Skip to content
This repository was archived by the owner on Aug 8, 2023. It is now read-only.

[darwin] Remove unnecessary MGLTileSource initializers #8633

Closed
wants to merge 2 commits into from
Closed

[darwin] Remove unnecessary MGLTileSource initializers #8633

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6519f4d
[darwin] Remove unnecessary MGLTileSource initializers
jfirebaugh Apr 4, 2017
9b60317
[darwin] Simplify MGLSource initialization and pointer management
jfirebaugh Apr 4, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
103 changes: 103 additions & 0 deletions platform/darwin/src/MGLRasterSource.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,6 +104,109 @@ MGL_EXPORT
*/
- (instancetype)initWithIdentifier:(NSString *)identifier configurationURL:(NSURL *)configurationURL tileSize:(CGFloat)tileSize NS_DESIGNATED_INITIALIZER;

/**
Returns a raster 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
Copy link
Contributor

@1ec5 1ec5 Apr 4, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Redeclaring -initWithIdentifier:tileURLTemplates:options: in the abstract superclass gave us a common place to put this substantial amount of documentation. It’s important for the developer to know that the identically or similarly named initializers in the subclasses behave similarly – or even to think of MGLRasterSource and MGLVectorSource as sharing the same initializers – even if they don’t share the same implementation in mbgl under the hood (but the developer doesn’t need to know that).

If we need to eliminate the superclass method, we should at least factor this documentation out into a jazzy guide and link to it from each identical method instead of duplicating it. It would take the developer awhile to determine that both copies are the same.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's currently no indication in the documentation of how to initialize MGLVectorSource. I think this is an improvement, despite the duplication.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There’s the line @interface MGLVectorSource : MGLTileSource at the top, which links to the documentation for MGLTileSource. However, that page says “Do not create instances of this class directly”, which the developer may misinterpret to mean “don’t use these methods at all”. This is a shortcoming of our documentation for abstract classes in general (and of some of Apple’s own abstract class documentation).

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tracking as tail work in #8634 and more broadly in #8635.


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. 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.
@return An initialized tile source.
*/
- (instancetype)initWithIdentifier:(NSString *)identifier tileURLTemplates:(NS_ARRAY_OF(NSString *) *)tileURLTemplates options:(nullable NS_DICTIONARY_OF(MGLTileSourceOption, id) *)options NS_DESIGNATED_INITIALIZER;

@end
Expand Down
4 changes: 2 additions & 2 deletions platform/darwin/src/MGLRasterSource.mm
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ - (instancetype)initWithIdentifier:(NSString *)identifier configurationURL:(NSUR
}

- (instancetype)initWithIdentifier:(NSString *)identifier configurationURL:(NSURL *)configurationURL tileSize:(CGFloat)tileSize {
if (self = [super initWithIdentifier:identifier configurationURL:configurationURL]) {
if (self = [super initWithIdentifier:identifier]) {
auto source = std::make_unique<mbgl::style::RasterSource>(identifier.UTF8String,
configurationURL.mgl_URLByStandardizingScheme.absoluteString.UTF8String,
uint16_t(round(tileSize)));
Expand All @@ -48,7 +48,7 @@ - (instancetype)initWithIdentifier:(NSString *)identifier configurationURL:(NSUR
}

- (instancetype)initWithIdentifier:(NSString *)identifier tileURLTemplates:(NS_ARRAY_OF(NSString *) *)tileURLTemplates options:(nullable NS_DICTIONARY_OF(MGLTileSourceOption, id) *)options {
if (self = [super initWithIdentifier:identifier tileURLTemplates:tileURLTemplates options:options]) {
if (self = [super initWithIdentifier:identifier]) {
mbgl::Tileset tileSet = MGLTileSetFromTileURLTemplates(tileURLTemplates, options);

uint16_t tileSize = MGLRasterSourceRetinaTileSize;
Expand Down
129 changes: 0 additions & 129 deletions platform/darwin/src/MGLTileSource.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -147,135 +147,6 @@ typedef NS_ENUM(NSUInteger, MGLTileCoordinateSystem) {
MGL_EXPORT
@interface MGLTileSource : MGLSource

#pragma mark Initializing a Source

- (instancetype)init __attribute__((unavailable("Use -initWithIdentifier:configurationURL: or -initWithIdentifier:tileURLTemplates:options: instead.")));
- (instancetype)initWithIdentifier:(NSString *)identifier __attribute__((unavailable("Use -initWithIdentifier:configurationURL: or -initWithIdentifier:tileURLTemplates:options: instead.")));

/**
Returns a tile source initialized with an identifier and configuration URL.

After initializing and configuring the source, add it to a map view’s style
using the `-[MGLStyle addSource:]` method.

The URL may be a full HTTP or HTTPS URL or, for tile sets hosted by Mapbox, a
Mapbox URL indicating a map identifier (`mapbox://<mapid>`). The URL should
point to a JSON file that conforms to the
<a href="https://github.com/mapbox/tilejson-spec/">TileJSON specification</a>.

@param identifier A string that uniquely identifies the source in the style to
which it is added.
@param configurationURL A URL to a TileJSON configuration file describing the
source’s contents and other metadata.
@return An initialized tile source.
*/
- (instancetype)initWithIdentifier:(NSString *)identifier configurationURL:(NSURL *)configurationURL;

/**
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. 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.
@return An initialized tile source.
*/
- (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

/**
Expand Down
8 changes: 0 additions & 8 deletions platform/darwin/src/MGLTileSource.mm
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,14 +19,6 @@

@implementation MGLTileSource

- (instancetype)initWithIdentifier:(NSString *)identifier configurationURL:(NSURL *)configurationURL {
return [super initWithIdentifier:identifier];
}

- (instancetype)initWithIdentifier:(NSString *)identifier tileURLTemplates:(NS_ARRAY_OF(NSString *) *)tileURLTemplates options:(NS_DICTIONARY_OF(MGLTileSourceOption, id) *)options {
return [super initWithIdentifier:identifier];
}

- (NSURL *)configurationURL {
[NSException raise:@"MGLAbstractClassException"
format:@"MGLTileSource is an abstract class"];
Expand Down
Loading