[ios, macos] add tileset encoding option to darwin sources (#11274)

* add tileset encoding option to darwin sources

* correct style guide

* link out to dem encoding docs

* markdownify comments

platform/darwin/docs/guides/For Style Authors.md.ejs

@@ -205,6 +205,7 @@ In style JSON | In TileJSON   | In the SDK
 `tileSize`    | —             | `MGLTileSourceOptionTileSize`
 `attribution` | `attribution` | `MGLTileSourceOptionAttributionHTMLString` (but consider specifying `MGLTileSourceOptionAttributionInfos` instead for improved security)
 `scheme`      | `scheme`      | `MGLTileSourceOptionTileCoordinateSystem`
+`encoding`    | –             | `MGLTileSourceOptionDEMEncoding`
 
 ### Shape sources
 

platform/darwin/src/MGLTileSource.h

@@ -117,6 +117,7 @@ extern MGL_EXPORT const MGLTileSourceOption MGLTileSourceOptionAttributionInfos;
  */
 extern MGL_EXPORT const MGLTileSourceOption MGLTileSourceOptionTileCoordinateSystem;
 
+
 /**
  Tile coordinate systems that determine how tile coordinates in tile URLs are
  interpreted.
@@ -141,6 +142,35 @@ typedef NS_ENUM(NSUInteger, MGLTileCoordinateSystem) {
     MGLTileCoordinateSystemTMS
 };
 
+
+/**
+ An `NSNumber` object containing an unsigned integer that specifies the encoding
+ formula for raster-dem tilesets. The integer corresponds to one of
+ the constants described in `MGLDEMEncoding`.
+
+ The default value for this option is `MGLDEMEncodingMapbox`.
+
+ This option is not supported by the TileJSON spec.
+ */
+extern MGL_EXPORT const MGLTileSourceOption MGLTileSourceOptionDEMEncoding;
+
+/**
+ The encoding formula used to generate the raster-dem tileset
+*/
+
+typedef NS_ENUM(NSUInteger, MGLDEMEncoding) {
+
+    /**
+     Raster tiles generated with the [Mapbox encoding formula](https://www.mapbox.com/help/access-elevation-data/#mapbox-terrain-rgb).
+    */
+    MGLDEMEncodingMapbox = 0,
+
+    /**
+     Raster tiles generated with the [Mapzen Terrarium encoding formula](https://aws.amazon.com/public-datasets/terrain/).
+    */
+    MGLDEMEncodingTerrarium
+};
+
 /**
  `MGLTileSource` is a map content source that supplies map tiles to be shown on
  the map. The location of and metadata about the tiles are defined either by an

platform/darwin/src/MGLTileSource.mm

@@ -19,6 +19,7 @@ const MGLTileSourceOption MGLTileSourceOptionCoordinateBounds = @"MGLTileSourceO
 const MGLTileSourceOption MGLTileSourceOptionAttributionHTMLString = @"MGLTileSourceOptionAttributionHTMLString";
 const MGLTileSourceOption MGLTileSourceOptionAttributionInfos = @"MGLTileSourceOptionAttributionInfos";
 const MGLTileSourceOption MGLTileSourceOptionTileCoordinateSystem = @"MGLTileSourceOptionTileCoordinateSystem";
+const MGLTileSourceOption MGLTileSourceOptionDEMEncoding = @"MGLTileSourceOptionDEMEncoding";
 
 @implementation MGLTileSource
 
@@ -129,5 +130,22 @@ mbgl::Tileset MGLTileSetFromTileURLTemplates(NS_ARRAY_OF(NSString *) *tileURLTem
         }
     }
 
+    if (NSNumber *demEncodingNumber = options[MGLTileSourceOptionDEMEncoding]) {
+        if (![demEncodingNumber isKindOfClass:[NSValue class]]) {
+            [NSException raise:NSInvalidArgumentException
+                        format:@"MGLTileSourceOptionDEMEncoding must be set to an NSValue or NSNumber."];
+        }
+        MGLDEMEncoding demEncoding;
+        [demEncodingNumber getValue:&demEncoding];
+        switch (demEncoding) {
+            case MGLDEMEncodingMapbox:
+                tileSet.encoding = mbgl::Tileset::DEMEncoding::Mapbox;
+                break;
+            case MGLDEMEncodingTerrarium:
+                tileSet.encoding = mbgl::Tileset::DEMEncoding::Terrarium;
+                break;
+        }
+    }
+
     return tileSet;
 }

platform/darwin/test/MGLTileSetTests.mm

@@ -102,6 +102,23 @@
 
     // the scheme is reflected by the mbgl tileset
     XCTAssertEqual(tileSet.scheme, mbgl::Tileset::Scheme::TMS);
+
+    // when the dem enciding is changed using an NSNumber
+    tileSet = MGLTileSetFromTileURLTemplates(tileURLTemplates, @{
+        MGLTileSourceOptionDEMEncoding: @(MGLDEMEncodingTerrarium),
+    });
+
+    // the encoding is reflected by the mbgl tileset
+    XCTAssertEqual(tileSet.encoding, mbgl::Tileset::DEMEncoding::Terrarium);
+
+    // when the dem enciding is changed using an NSValue
+    MGLDEMEncoding terrarium = MGLDEMEncodingTerrarium;
+    tileSet = MGLTileSetFromTileURLTemplates(tileURLTemplates, @{
+        MGLTileSourceOptionDEMEncoding: [NSValue value:&terrarium withObjCType:@encode(MGLDEMEncoding)],
+    });
+
+    // the encoding is reflected by the mbgl tileset
+    XCTAssertEqual(tileSet.encoding, mbgl::Tileset::DEMEncoding::Terrarium);
 }
 
 - (void)testInvalidTileSet {

platform/ios/docs/guides/For Style Authors.md

@@ -154,6 +154,7 @@ In style JSON | In TileJSON   | In the SDK
 `tileSize`    | —             | `MGLTileSourceOptionTileSize`
 `attribution` | `attribution` | `MGLTileSourceOptionAttributionHTMLString` (but consider specifying `MGLTileSourceOptionAttributionInfos` instead for improved security)
 `scheme`      | `scheme`      | `MGLTileSourceOptionTileCoordinateSystem`
+`encoding`    | –             | `MGLTileSourceOptionDEMEncoding`
 
 ### Shape sources
 

platform/macos/docs/guides/For Style Authors.md

@@ -141,6 +141,7 @@ In style JSON | In TileJSON   | In the SDK
 `tileSize`    | —             | `MGLTileSourceOptionTileSize`
 `attribution` | `attribution` | `MGLTileSourceOptionAttributionHTMLString` (but consider specifying `MGLTileSourceOptionAttributionInfos` instead for improved security)
 `scheme`      | `scheme`      | `MGLTileSourceOptionTileCoordinateSystem`
+`encoding`    | –             | `MGLTileSourceOptionDEMEncoding`
 
 ### Shape sources