[ios, macos] Added option to restrict tile source to bounds

Cherry-picked from c3bf7c55a1f648e57c3853d555ff5f63c989f8c4.

8 files changed, 55 insertions, 1 deletions

diff --git a/platform/darwin/docs/guides/For Style Authors.md.ejs b/platform/darwin/docs/guides/For Style Authors.md.ejs
index 06a8907704..ba6f14647c 100644
--- a/platform/darwin/docs/guides/For Style Authors.md.ejs
+++ b/platform/darwin/docs/guides/For Style Authors.md.ejs
@@ -160,6 +160,7 @@ the following terms for concepts defined in the style specification:
 
 In the style specification | In the SDK
 ---------------------------|---------
+bounds                     | coordinate bounds
 filter                     | predicate
 function type              | interpolation mode
 id                         | identifier
@@ -200,6 +201,7 @@ In style JSON | In TileJSON   | In the SDK
 `tiles`       | `tiles`       | `tileURLTemplates` parameter in `-[MGLTileSource initWithIdentifier:tileURLTemplates:options:]`
 `minzoom`     | `minzoom`     | `MGLTileSourceOptionMinimumZoomLevel`
 `maxzoom`     | `maxzoom`     | `MGLTileSourceOptionMaximumZoomLevel`
+`bounds`      | `bounds`      | `MGLTileSourceOptionCoordinateBounds`
 `tileSize`    | —             | `MGLTileSourceOptionTileSize`
 `attribution` | `attribution` | `MGLTileSourceOptionAttributionHTMLString` (but consider specifying `MGLTileSourceOptionAttributionInfos` instead for improved security)
 `scheme`      | `scheme`      | `MGLTileSourceOptionTileCoordinateSystem`
diff --git a/platform/darwin/src/MGLTileSource.h b/platform/darwin/src/MGLTileSource.h
index caeafcd2f6..3dc268db60 100644
--- a/platform/darwin/src/MGLTileSource.h
+++ b/platform/darwin/src/MGLTileSource.h
@@ -41,6 +41,20 @@ extern MGL_EXPORT const MGLTileSourceOption MGLTileSourceOptionMinimumZoomLevel;
  */
 extern MGL_EXPORT const MGLTileSourceOption MGLTileSourceOptionMaximumZoomLevel;
 
+/**
+ An `NSValue` object containing an `MGLCoordinateBounds` struct that specifies
+ the geographic extent of the source.
+ 
+ If this option is specified, the SDK avoids requesting any tile that falls
+ outside of the coordinate bounds. Otherwise, the SDK requests any tile needed
+ to cover the viewport, as it does by default.
+
+ This option corresponds to the `bounds` key in the
+ <a href="https://github.com/mapbox/tilejson-spec/tree/master/2.1.0">TileJSON</a>
+ specification.
+ */
+extern MGL_EXPORT const MGLTileSourceOption MGLTileSourceOptionCoordinateBounds;
+
 #if TARGET_OS_IPHONE
 /**
  An HTML string defining the buttons to be displayed in an action sheet when the
diff --git a/platform/darwin/src/MGLTileSource.mm b/platform/darwin/src/MGLTileSource.mm
index 5644ad9a06..bc985bd728 100644
--- a/platform/darwin/src/MGLTileSource.mm
+++ b/platform/darwin/src/MGLTileSource.mm
@@ -1,7 +1,9 @@
 #import "MGLTileSource_Private.h"
 
 #import "MGLAttributionInfo_Private.h"
+#import "MGLGeometry_Private.h"
 #import "NSString+MGLAdditions.h"
+#import "NSValue+MGLAdditions.h"
 
 #if TARGET_OS_IPHONE
     #import <UIKit/UIKit.h>
@@ -13,6 +15,7 @@
 
 const MGLTileSourceOption MGLTileSourceOptionMinimumZoomLevel = @"MGLTileSourceOptionMinimumZoomLevel";
 const MGLTileSourceOption MGLTileSourceOptionMaximumZoomLevel = @"MGLTileSourceOptionMaximumZoomLevel";
+const MGLTileSourceOption MGLTileSourceOptionCoordinateBounds = @"MGLTileSourceOptionCoordinateBounds";
 const MGLTileSourceOption MGLTileSourceOptionAttributionHTMLString = @"MGLTileSourceOptionAttributionHTMLString";
 const MGLTileSourceOption MGLTileSourceOptionAttributionInfos = @"MGLTileSourceOptionAttributionInfos";
 const MGLTileSourceOption MGLTileSourceOptionTileCoordinateSystem = @"MGLTileSourceOptionTileCoordinateSystem";
@@ -70,6 +73,15 @@ mbgl::Tileset MGLTileSetFromTileURLTemplates(NS_ARRAY_OF(NSString *) *tileURLTem
         [NSException raise:NSInvalidArgumentException
                     format:@"MGLTileSourceOptionMinimumZoomLevel must be less than MGLTileSourceOptionMaximumZoomLevel."];
     }
+    
+    if (NSValue *coordinateBounds = options[MGLTileSourceOptionCoordinateBounds]) {
+        if (![coordinateBounds isKindOfClass:[NSValue class]]
+            && strcmp(coordinateBounds.objCType, @encode(MGLCoordinateBounds)) == 0) {
+            [NSException raise:NSInvalidArgumentException
+                        format:@"MGLTileSourceOptionCoordinateBounds must be set to an NSValue containing an MGLCoordinateBounds."];
+        }
+        tileSet.bounds = MGLLatLngBoundsFromCoordinateBounds(coordinateBounds.MGLCoordinateBoundsValue);
+    }
 
     if (NSString *attribution = options[MGLTileSourceOptionAttributionHTMLString]) {
         if (![attribution isKindOfClass:[NSString class]]) {
diff --git a/platform/darwin/test/MGLTileSetTests.mm b/platform/darwin/test/MGLTileSetTests.mm
index 40eab5f974..4d5e1fcd05 100644
--- a/platform/darwin/test/MGLTileSetTests.mm
+++ b/platform/darwin/test/MGLTileSetTests.mm
@@ -2,6 +2,7 @@
 
 #import <Mapbox/Mapbox.h>
 #import "MGLTileSource_Private.h"
+#import "MGLGeometry_Private.h"
 
 #include <mbgl/util/tileset.hpp>
 
@@ -40,6 +41,19 @@
     XCTAssertEqual(tileSet.zoomRange.min, 1);
     XCTAssertEqual(tileSet.zoomRange.max, 2);
 
+    // when the tile set has a bounds set
+    MGLCoordinateBounds bounds = MGLCoordinateBoundsMake(CLLocationCoordinate2DMake(12, 34), CLLocationCoordinate2DMake(56, 78));
+    tileSet = MGLTileSetFromTileURLTemplates(@[@"tile.1"], @{
+        MGLTileSourceOptionCoordinateBounds: @(bounds),
+    });
+
+    // the mbgl object reflects the set values for the bounds
+    XCTAssert(!!tileSet.bounds, @"The bounds are set after setting the bounds");
+    if (tileSet.bounds) {
+        MGLCoordinateBounds actual = MGLCoordinateBoundsFromLatLngBounds(*tileSet.bounds);
+        XCTAssert(MGLCoordinateBoundsEqualToCoordinateBounds(bounds, actual), @"The bounds round-trip");
+    }
+
     // when the tile set has an attribution
     NSString *attribution = @"my tileset © ©️🎈";
     tileSet = MGLTileSetFromTileURLTemplates(tileURLTemplates, @{
diff --git a/platform/ios/CHANGELOG.md b/platform/ios/CHANGELOG.md
index 292075f0c0..7eb3fd8bf9 100644
--- a/platform/ios/CHANGELOG.md
+++ b/platform/ios/CHANGELOG.md
@@ -2,7 +2,11 @@
 
 Mapbox welcomes participation and contributions from everyone. Please read [CONTRIBUTING.md](../../CONTRIBUTING.md) to get started.
 
-## 3.7.3
+## 3.7.4
+
+* Added the `MGLTileSourceOptionTileCoordinateBounds` option to create an `MGLTileSource` that only supplies tiles within a specific geographic bounding box. ([#11141](https://github.com/mapbox/mapbox-gl-native/pull/11141))
+
+## 3.7.3 - January 10, 2018
 
 * Fixed a crash while zooming while annotations are present on the map. ([#10791](https://github.com/mapbox/mapbox-gl-native/pull/10791))
 * CJK characters can be displayed in a locally installed font or a custom font bundled with the application, reducing map download times. Specify the font name using the `MGLIdeographicFontFamilyName` key in the application’s Info.plist file. ([#10522](https://github.com/mapbox/mapbox-gl-native/pull/10522))
diff --git a/platform/ios/docs/guides/For Style Authors.md b/platform/ios/docs/guides/For Style Authors.md
index 7eabfed777..ebf4eb23d6 100644
--- a/platform/ios/docs/guides/For Style Authors.md
+++ b/platform/ios/docs/guides/For Style Authors.md
@@ -109,6 +109,7 @@ the following terms for concepts defined in the style specification:
 
 In the style specification | In the SDK
 ---------------------------|---------
+bounds                     | coordinate bounds
 filter                     | predicate
 function type              | interpolation mode
 id                         | identifier
@@ -149,6 +150,7 @@ In style JSON | In TileJSON   | In the SDK
 `tiles`       | `tiles`       | `tileURLTemplates` parameter in `-[MGLTileSource initWithIdentifier:tileURLTemplates:options:]`
 `minzoom`     | `minzoom`     | `MGLTileSourceOptionMinimumZoomLevel`
 `maxzoom`     | `maxzoom`     | `MGLTileSourceOptionMaximumZoomLevel`
+`bounds`      | `bounds`      | `MGLTileSourceOptionCoordinateBounds`
 `tileSize`    | —             | `MGLTileSourceOptionTileSize`
 `attribution` | `attribution` | `MGLTileSourceOptionAttributionHTMLString` (but consider specifying `MGLTileSourceOptionAttributionInfos` instead for improved security)
 `scheme`      | `scheme`      | `MGLTileSourceOptionTileCoordinateSystem`
diff --git a/platform/macos/CHANGELOG.md b/platform/macos/CHANGELOG.md
index 7a2c47cede..24abafdaaf 100644
--- a/platform/macos/CHANGELOG.md
+++ b/platform/macos/CHANGELOG.md
@@ -1,5 +1,9 @@
 # Changelog for Mapbox Maps SDK for macOS
 
+## v0.6.2
+
+* Added the `MGLTileSourceOptionTileCoordinateBounds` option to create an `MGLTileSource` that only supplies tiles within a specific geographic bounding box. ([#11141](https://github.com/mapbox/mapbox-gl-native/pull/11141))
+
 ## v0.6.1 - January 16, 2018
 
 This version of the Mapbox macOS SDK corresponds to version 3.7.3 of the Mapbox Maps SDK for iOS.
diff --git a/platform/macos/docs/guides/For Style Authors.md b/platform/macos/docs/guides/For Style Authors.md
index 3cacc81376..d1b08f74a9 100644
--- a/platform/macos/docs/guides/For Style Authors.md
+++ b/platform/macos/docs/guides/For Style Authors.md
@@ -96,6 +96,7 @@ the following terms for concepts defined in the style specification:
 
 In the style specification | In the SDK
 ---------------------------|---------
+bounds                     | coordinate bounds
 filter                     | predicate
 function type              | interpolation mode
 id                         | identifier
@@ -136,6 +137,7 @@ In style JSON | In TileJSON   | In the SDK
 `tiles`       | `tiles`       | `tileURLTemplates` parameter in `-[MGLTileSource initWithIdentifier:tileURLTemplates:options:]`
 `minzoom`     | `minzoom`     | `MGLTileSourceOptionMinimumZoomLevel`
 `maxzoom`     | `maxzoom`     | `MGLTileSourceOptionMaximumZoomLevel`
+`bounds`      | `bounds`      | `MGLTileSourceOptionCoordinateBounds`
 `tileSize`    | —             | `MGLTileSourceOptionTileSize`
 `attribution` | `attribution` | `MGLTileSourceOptionAttributionHTMLString` (but consider specifying `MGLTileSourceOptionAttributionInfos` instead for improved security)
 `scheme`      | `scheme`      | `MGLTileSourceOptionTileCoordinateSystem`