Rename screen shape (#3377)

evil159 · jakra-mb · github-actions[bot] · commit 882451718c8c · 2025-04-23T08:41:15.000Z
### GL native * Rename screen shape to screen culling shape * Use Vec2 instead of screen coordinate * Remove culling shape from init options ### Maps iOS * Expose API to set screen culling shape | iOS | Android | | --- | --- | | <video src="https://github.com/user-attachments/assets/e3d4acb8-01b1-4c53-ba76-8e05ff085426"> | <video src="https://github.com/user-attachments/assets/33122660-65ba-4f31-8eae-d180fe630c14"> | Addresses: https://mapbox.atlassian.net/browse/MAPSIOS-1811 and https://mapbox.atlassian.net/browse/MAPSAND-2119 cc @mapbox/sdk-ci --------- Co-authored-by: Jan Krassnigg <jan.krassnigg@mapbox.com> GitOrigin-RevId: 68a34816e8e5bacf61a119eb2503fc2cba59337c
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,8 @@ Mapbox welcomes participation and contributions from everyone.
 
 ## main
 
+* Expose an experimental API to define a non-rectangular screen culling shape(`MapboxMap.screenCullingShape`).
+
 ## 11.12.0-beta.1 - 9 April, 2025
 
 * Expose `graphicsPrograms`, `graphicsProgramsCreationTimeMillis` and `fboSwitchCount` for `CumulativeRenderingStatistics`.
@@ -17,7 +19,7 @@ Mapbox welcomes participation and contributions from everyone.
 ## 11.11.0-rc.1 – 12 March, 2025
 
 * Expose experimental API for setting ColorTheme on style imports.
-* Expose use-theme properties for all annotation types and Puck3D layer. 
+* Expose use-theme properties for all annotation types and Puck3D layer.
 * Update CoreMaps to 11.11.0-rc.2.
 * Update Common to 24.11.0-rc.2.
 
diff --git a/LICENSE.md b/LICENSE.md
diff --git a/MapboxMaps.podspec b/MapboxMaps.podspec
@@ -19,8 +19,8 @@ Pod::Spec.new do |m|
   m.source_files = 'Sources/MapboxMaps/**/*.{swift,h}'
   m.resource_bundles = { 'MapboxMapsResources' => ['Sources/MapboxMaps/**/*.{xcassets,strings}', 'Sources/MapboxMaps/MapboxMaps.json', 'Sources/MapboxMaps/PrivacyInfo.xcprivacy'] }
 
-  m.dependency 'MapboxCoreMaps', '11.13.0-SNAPSHOT-04-23--04-29.git-3eea307'
-  m.dependency 'MapboxCommon', '24.13.0-SNAPSHOT-04-23--04-29.git-3eea307'
+  m.dependency 'MapboxCoreMaps', '11.13.0-SNAPSHOT-04-23--05-20.git-ad48dc8'
+  m.dependency 'MapboxCommon', '24.13.0-SNAPSHOT-04-23--05-20.git-ad48dc8'
   m.dependency 'Turf', '4.0.0'
 
 end
diff --git a/Package.swift b/Package.swift
@@ -4,8 +4,8 @@
 import PackageDescription
 import Foundation
 
-let commonVersion: Version = "24.13.0-SNAPSHOT-04-23--04-29.git-3eea307"
-let coreMapsVersion: Version = "11.13.0-SNAPSHOT-04-23--04-29.git-3eea307"
+let commonVersion: Version = "24.13.0-SNAPSHOT-04-23--05-20.git-ad48dc8"
+let coreMapsVersion: Version = "11.13.0-SNAPSHOT-04-23--05-20.git-ad48dc8"
 let turfVersion: Version = "4.0.0"
 
 let mapboxMapsPath: String? = nil
diff --git a/Sources/Examples/All Examples/DebugMapExample.swift b/Sources/Examples/All Examples/DebugMapExample.swift
@@ -17,8 +17,37 @@ final class DebugMapExample: UIViewController, ExampleProtocol {
         Setting(option: .debug(.light), title: "Show light conditions"),
         Setting(option: .debug(.camera), title: "Show camera debug view"),
         Setting(option: .debug(.padding), title: "Camera padding"),
+        Setting(option: .screenShape, title: "Custom culling shape"),
         Setting(option: .performance(.init([.perFrame, .cumulative], samplingDurationMillis: 5000)), title: "Performance statistics"),
     ]
+    private let customCullingShapeLayer: CAShapeLayer = {
+        let layer = CAShapeLayer()
+        layer.strokeColor = UIColor.white.cgColor
+        layer.fillColor = UIColor.clear.cgColor
+        layer.lineWidth = 3
+        layer.lineJoin = .round
+        layer.shadowColor = UIColor.white.cgColor
+        layer.shadowRadius = 5
+        layer.shadowOpacity = 1
+        layer.shouldRasterize = true
+        layer.rasterizationScale = UIScreen.main.scale
+        return layer
+    }()
+    private let dimLayer: CAShapeLayer = {
+        let layer = CAShapeLayer()
+        layer.fillRule = .evenOdd
+        layer.fillColor = UIColor.black.withAlphaComponent(0.5).cgColor
+
+        return layer
+    }()
+    private let customCullingShape = [
+        CGPoint(x: 0.35, y: 0.34),  // top-left
+        CGPoint(x: 0.65, y: 0.34),  // top-right
+        CGPoint(x: 0.85, y: 0.50),  // right
+        CGPoint(x: 0.65, y: 0.66),  // bottom-right
+        CGPoint(x: 0.35, y: 0.66),  // bottom-left
+        CGPoint(x: 0.15, y: 0.50)   // left
+    ]
 
     override func viewDidLoad() {
         super.viewDidLoad()
@@ -76,10 +105,49 @@ final class DebugMapExample: UIViewController, ExampleProtocol {
     private func handle(statistics: PerformanceStatistics) {
         showAlert(with: "\(statistics.topRenderedGroupDescription)\n\(statistics.renderingDurationStatisticsDescription)")
     }
+
+    override func viewDidLayoutSubviews() {
+        super.viewDidLayoutSubviews()
+
+        let scaledShape = customCullingShape.map { CGPoint(x: $0.x * mapView.bounds.width, y: $0.y * mapView.bounds.height) }
+        let cutoutPath = UIBezierPath()
+        cutoutPath.move(to: scaledShape.first!)
+        scaledShape.dropFirst().forEach(cutoutPath.addLine)
+        cutoutPath.close()
+
+        customCullingShapeLayer.path = cutoutPath.cgPath
+
+        let mapViewPath = UIBezierPath(rect: mapView.bounds)
+        mapViewPath.append(cutoutPath)
+        mapViewPath.usesEvenOddFillRule = true
+
+        dimLayer.path = mapViewPath.cgPath
+    }
+
+    private func setScreenShape() {
+        mapView.mapboxMap.screenCullingShape = customCullingShape
+        mapView.layer.addSublayer(dimLayer)
+        mapView.layer.addSublayer(customCullingShapeLayer)
+    }
+
+    private func removeScreenShape() {
+        customCullingShapeLayer.removeFromSuperlayer()
+        dimLayer.removeFromSuperlayer()
+        mapView.mapboxMap.screenCullingShape = []
+    }
 }
 
 extension DebugMapExample: DebugOptionSettingsDelegate {
-    func settingsDidChange(debugOptions: MapViewDebugOptions, performanceOptions: PerformanceStatisticsOptions?) {
+    func settingsDidChange(
+        debugOptions: MapViewDebugOptions,
+        performanceOptions: PerformanceStatisticsOptions?,
+        screenShapeEnabled: Bool
+    ) {
+        if screenShapeEnabled {
+            setScreenShape()
+        } else {
+            removeScreenShape()
+        }
         mapView.debugOptions = debugOptions
 
         guard let performanceOptions else { return performanceStatisticsCancelable = nil }
@@ -133,16 +201,21 @@ final class SettingsViewController: UIViewController, UITableViewDataSource {
     }
 
     @objc private func saveSettings(_ sender: UIBarButtonItem) {
-        let debugOptions = settings
-            .filter(\.isEnabled)
+        let enabledSettings = settings.filter({ $0.isEnabled })
+        let debugOptions = enabledSettings
             .compactMap(\.option.debugOption)
             .reduce(MapViewDebugOptions()) { result, next in result.union(next) }
 
-        let performanceOptions = settings
-            .filter(\.isEnabled)
+        let performanceOptions = enabledSettings
             .compactMap(\.option.performanceOption)
 
-        delegate?.settingsDidChange(debugOptions: debugOptions, performanceOptions: performanceOptions.first)
+        let screenShapeEnabled = enabledSettings.contains(where: { $0.option.isScreenShape })
+
+        delegate?.settingsDidChange(
+            debugOptions: debugOptions,
+            performanceOptions: performanceOptions.first,
+            screenShapeEnabled: screenShapeEnabled
+        )
         dismiss(animated: true, completion: nil)
     }
 
@@ -211,13 +284,18 @@ private class DebugOptionCell: UITableViewCell {
 }
 
 protocol DebugOptionSettingsDelegate: AnyObject {
-    func settingsDidChange(debugOptions: MapViewDebugOptions, performanceOptions: PerformanceStatisticsOptions?)
+    func settingsDidChange(
+        debugOptions: MapViewDebugOptions,
+        performanceOptions: PerformanceStatisticsOptions?,
+        screenShapeEnabled: Bool
+    )
 }
 
 private final class Setting {
     enum Option {
         case debug(MapViewDebugOptions)
         case performance(PerformanceStatisticsOptions)
+        case screenShape
     }
 
     let option: Option
@@ -241,6 +319,10 @@ extension Setting.Option {
     var performanceOption: PerformanceStatisticsOptions? {
         if case let .performance(option) = self { return option } else { return nil }
     }
+
+    var isScreenShape: Bool {
+        if case .screenShape = self { return true } else { return false }
+    }
 }
 
 extension PerformanceStatistics {
diff --git a/Sources/MapboxMaps/Documentation.docc/API Catalogs/Free Camera.md b/Sources/MapboxMaps/Documentation.docc/API Catalogs/Free Camera.md
@@ -4,5 +4,6 @@
 
 ### Symbols
 
+- ``Vec2``
 - ``Vec3``
 - ``Vec4``
diff --git a/Sources/MapboxMaps/Foundation/Extensions/Core/MapOptions.swift b/Sources/MapboxMaps/Foundation/Extensions/Core/MapOptions.swift
@@ -64,8 +64,7 @@ extension MapOptions {
                   crossSourceCollisions: crossSourceCollisions.NSNumber,
                   size: mbmSize,
                   pixelRatio: Float(pixelRatio ?? ScreenShim.nativeScale),
-                  glyphsRasterizationOptions: glyphsRasterizationOptions,
-                  screenShape: nil)
+                  glyphsRasterizationOptions: glyphsRasterizationOptions)
     }
 
     /// The map constrain mode. This can be used to limit the map to wrap around
diff --git a/Sources/MapboxMaps/Foundation/Extensions/Core/Vec2.swift b/Sources/MapboxMaps/Foundation/Extensions/Core/Vec2.swift
@@ -0,0 +1,8 @@
+import Foundation
+import MapboxCoreMaps
+
+extension Vec2 {
+    var point: CGPoint {
+        CGPoint(x: x, y: y)
+    }
+}
diff --git a/Sources/MapboxMaps/Foundation/Extensions/CoreGraphics.swift b/Sources/MapboxMaps/Foundation/Extensions/CoreGraphics.swift
@@ -11,6 +11,10 @@ extension CGPoint {
         CoreScreenCoordinate(x: Double(x), y: Double(y))
     }
 
+    internal var vec2: Vec2 {
+        Vec2(x: x, y: y)
+    }
+
     /// Interpolate a point along a fraction of a line between two points.
     /// - Parameters:
     ///   - origin: The starting point for the interpolation.
diff --git a/Sources/MapboxMaps/Foundation/MapInitOptions.swift b/Sources/MapboxMaps/Foundation/MapInitOptions.swift
@@ -1,4 +1,5 @@
 import Foundation
+@_implementationOnly import MapboxCoreMaps_Private
 
 /// A protocol used to provide ``MapInitOptions`` when initializing a ``MapView`` with a Storyboard or
 /// a nib.
@@ -101,9 +102,7 @@ extension MapInitOptions {
                 crossSourceCollisions: mapOptions.__crossSourceCollisions,
                 size: Size(width: Float(bounds.width), height: Float(bounds.height)),
                 pixelRatio: mapOptions.pixelRatio,
-                glyphsRasterizationOptions: mapOptions.glyphsRasterizationOptions,
-                screenShape: nil)
-
+                glyphsRasterizationOptions: mapOptions.glyphsRasterizationOptions)
 
             // Use the overriding style URI if provided (currently from IB)
             let resolvedStyleURI = overridingStyleURI.map { StyleURI(url: $0) } ?? styleURI
diff --git a/Sources/MapboxMaps/Foundation/MapboxMap.swift b/Sources/MapboxMaps/Foundation/MapboxMap.swift
@@ -346,6 +346,17 @@ public final class MapboxMap: StyleManager {
         __map.__setTileCacheBudgetFor(tileCacheBudget)
     }
 
+    /// A convex polygon that describes the shape of the screen in case it is non-rectangular.
+    /// Every coordinate is in 0 to 1 range, with (0, 0) being the map view top-left and (1, 1) the bottom-right.
+    /// The points have to be given in clockwise winding order. The polygon will be closed automatically, so for a rectangular shape, pass in 4 points.
+    /// Use this if the visible screen area is obscured enough that using a custom shape improves performance.
+    @_documentation(visibility: public)
+    @_spi(Experimental)
+    public var screenCullingShape: [CGPoint] {
+        get { __map.getScreenCullingShape().map(\.point) }
+        set { __map.setScreenCullingShapeForShape(newValue.map(\.vec2)) }
+    }
+
     /// Defines whether multiple copies of the world will be rendered side by side beyond -180 and 180 degrees longitude.
     ///
     /// If disabled, when the map is zoomed out far enough that a single representation of the world does not fill the map's entire container,
diff --git a/Tests/MapboxMapsTests/Foundation/MapboxMapTests.swift b/Tests/MapboxMapsTests/Foundation/MapboxMapTests.swift
@@ -53,8 +53,7 @@ final class MapboxMapTests: XCTestCase {
             crossSourceCollisions: mapInitOptions.mapOptions.crossSourceCollisions.NSNumber,
             size: mapInitOptions.mapOptions.size.map(Size.init),
             pixelRatio: mapInitOptions.mapOptions.pixelRatio,
-            glyphsRasterizationOptions: nil,
-            screenShape: nil) // __map.getOptions() always returns nil for glyphsRasterizationOptions
+            glyphsRasterizationOptions: nil) // __map.getOptions() always returns nil for glyphsRasterizationOptions
 
         let actualMapOptions = mapboxMap.options
 
@@ -114,6 +113,18 @@ final class MapboxMapTests: XCTestCase {
         XCTAssertEqual(mapboxMap.cameraState, CameraState(mapboxMap.__testingMap.getCameraState()))
     }
 
+    func testGetScreenCullingShape() {
+        let screenCullingShape = [CGPoint(x: 0, y: 0.5), CGPoint(x: 0.3, y: 0), CGPoint(x: 0.7, y: 1)]
+        mapboxMap.__testingMap.setScreenCullingShapeForShape(screenCullingShape.map(\.vec2))
+        XCTAssertEqual(mapboxMap.screenCullingShape, screenCullingShape)
+    }
+
+    func testSetScreenCullingShape() {
+        let screenCullingShape = [CGPoint(x: 0, y: 0.5), CGPoint(x: 0.3, y: 0), CGPoint(x: 0.7, y: 1)]
+        mapboxMap.screenCullingShape = screenCullingShape
+        XCTAssertEqual(mapboxMap.__testingMap.getScreenCullingShape(), screenCullingShape.map(\.vec2))
+    }
+
     func testCameraForCoordinateArray() {
         // A 1:1 square
         let southwest = CLLocationCoordinate2DMake(0, 0)
diff --git a/scripts/release/packager/versions.json b/scripts/release/packager/versions.json
@@ -1,5 +1,5 @@
 {
-    "MapboxCoreMaps": "11.13.0-SNAPSHOT-04-23--04-29.git-3eea307",
-    "MapboxCommon": "24.13.0-SNAPSHOT-04-23--04-29.git-3eea307",
+    "MapboxCoreMaps": "11.13.0-SNAPSHOT-04-23--05-20.git-ad48dc8",
+    "MapboxCommon": "24.13.0-SNAPSHOT-04-23--05-20.git-ad48dc8",
     "Turf": "4.0.0"
 }

Original file line number	Diff line number	Diff line change
`@@ -64,8 +64,7 @@ extension MapOptions {`
`64`	`64`	`crossSourceCollisions: crossSourceCollisions.NSNumber,`
`65`	`65`	`size: mbmSize,`
`66`	`66`	`pixelRatio: Float(pixelRatio ?? ScreenShim.nativeScale),`
`67`		`- glyphsRasterizationOptions: glyphsRasterizationOptions,`
`68`		`- screenShape: nil)`
	`67`	`+ glyphsRasterizationOptions: glyphsRasterizationOptions)`
`69`	`68`	`}`
`70`	`69`
`71`	`70`	`/// The map constrain mode. This can be used to limit the map to wrap around`