Expose maxOverscaleFactorForParentTiles for custom raster source (#…

…2421)

Co-authored-by: Patrick Leonard <[email protected]>

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 Mapbox welcomes participation and contributions from everyone.
 
+## main
+
+* Added support for the `maxOverscaleFactorForParentTiles` property in `CustomRasterSource`, allowing greater control over tile overscaling behavior when rendering custom raster tiles.
+
 ## 11.10.0-beta.1 - 20 January, 2025
 
 * Mark `SymbolElevationReference`, `FillExtrusionBaseAlignment`, `FillExtrusionHeightAlignment`,  `ModelScaleMode`, `ModelType`, `ClipLayerTypes`, `BackgroundPitchAlignment` types as Experimental. Initially they were exposed as stable by mistake. If you use them, please import `MapboxMaps` with `Experimental` SPI:

Sources/MapboxMaps/Style/CustomSources/CustomRasterSource.swift

@@ -19,30 +19,49 @@ public struct CustomRasterSource: Source, Equatable {
     @_documentation(visibility: public)
     public let options: CustomRasterSourceOptions?
 
+    /// When a set of tiles for a current zoom level is being rendered and some of the ideal tiles that cover the screen are not yet loaded, parent tiles could be used instead. Note that this might introduce unwanted rendering side-effects, especially for raster tiles that are overscaled multiple times. This property sets the maximum limit for how much a parent tile can be overscaled.
     @_documentation(visibility: public)
-    public init(id: String, options: CustomRasterSourceOptions) {
+    public var maxOverscaleFactorForParentTiles: UInt8?
+
+    @_documentation(visibility: public)
+    public init(id: String, options: CustomRasterSourceOptions, maxOverscaleFactorForParentTiles: UInt8? = nil) {
         self.id = id
         self.options = options
+        self.maxOverscaleFactorForParentTiles = maxOverscaleFactorForParentTiles
     }
 }
 
 extension CustomRasterSource {
     enum CodingKeys: String, CodingKey {
         case id
         case type
+        case maxOverscaleFactorForParentTiles = "max-overscale-factor-for-parent-tiles"
     }
 
     /// Init from a decoder, note that the CustomRasterSourceOptions are not decodable and need to be set separately
     public init(from decoder: Decoder) throws {
         let container = try decoder.container(keyedBy: CodingKeys.self)
         id = try container.decode(String.self, forKey: .id)
         options = nil
+        maxOverscaleFactorForParentTiles = try container.decodeIfPresent(UInt8.self, forKey: .maxOverscaleFactorForParentTiles)
     }
 
     /// Encode, note that options will not be included
     public func encode(to encoder: Encoder) throws {
         var container = encoder.container(keyedBy: CodingKeys.self)
-        try encodeNonVolatile(to: encoder, into: &container)
+
+        if encoder.userInfo[.volatilePropertiesOnly] as? Bool == true {
+            try encodeVolatile(to: encoder, into: &container)
+        } else if encoder.userInfo[.nonVolatilePropertiesOnly] as? Bool == true {
+            try encodeNonVolatile(to: encoder, into: &container)
+        } else {
+            try encodeVolatile(to: encoder, into: &container)
+            try encodeNonVolatile(to: encoder, into: &container)
+        }
+    }
+
+    private func encodeVolatile(to encoder: Encoder, into container: inout KeyedEncodingContainer<CodingKeys>) throws {
+        try container.encodeIfPresent(maxOverscaleFactorForParentTiles, forKey: .maxOverscaleFactorForParentTiles)
     }
 
     private func encodeNonVolatile(to encoder: Encoder, into container: inout KeyedEncodingContainer<CodingKeys>) throws {

Tests/MapboxMapsTests/Style/CustomSourcesIntegrationTests.swift

@@ -15,9 +15,14 @@ final class CustomSourcesIntegrationTests: MapViewIntegrationTestCase {
         let rasterOptions = CustomRasterSourceOptions(
             clientCallback: CustomRasterSourceClient.fromCustomRasterSourceTileStatusChangedCallback { _, _ in }
         )
+        let maxOverscaleFactorForParentTiles = UInt8(83)
 
         didFinishLoadingStyle = { mapView in
-            let source = CustomRasterSource(id: "test-source", options: rasterOptions)
+            let source = CustomRasterSource(
+                id: "test-source",
+                options: rasterOptions,
+                maxOverscaleFactorForParentTiles: maxOverscaleFactorForParentTiles
+            )
 
             // Add source
             do {
@@ -29,8 +34,9 @@ final class CustomSourcesIntegrationTests: MapViewIntegrationTestCase {
 
             // Retrieve the source
             do {
-                _ = try mapView.mapboxMap.source(withId: "test-source", type: CustomRasterSource.self)
+                let retrievedSource = try mapView.mapboxMap.source(withId: "test-source", type: CustomRasterSource.self)
 
+                XCTAssertEqual(retrievedSource.maxOverscaleFactorForParentTiles, maxOverscaleFactorForParentTiles)
                 successfullyRetrievedSourceExpectation.fulfill()
             } catch {
                 XCTFail("Failed to retrieve CustomRasterSource because of error: \(error)")

scripts/api-compatibility-check/breakage_allowlist.txt

@@ -2062,4 +2062,7 @@ Constructor ViewAnnotationOptions.init(annotatedFeature:width:height:allowOverla
 Func StyleManager.removeRain() is now with @_documentation
 Func StyleManager.removeSnow() is now with @_documentation
 Func StyleManager.setRain(_:) is now with @_documentation
-Func StyleManager.setSnow(_:) is now with @_documentation
+Func StyleManager.setSnow(_:) is now with @_documentation
+
+# Add maxOverscaleFactorForParentTiles to CustomRasterSource constructor
+Constructor CustomRasterSource.init(id:options:) has been removed