Expose screen culling shape for SwiftUI (#3529)

Address https://mapbox.atlassian.net/browse/MAPSIOS-1819

cc @mapbox/sdk-ci

GitOrigin-RevId: af6d1331f68aef6740dcf5e3f385b7052264e8d7

Author: evil159

Sources/Examples/SwiftUI Examples/Testing Examples/MapSettingsExample.swift

@@ -10,6 +10,7 @@ struct Settings {
     var ornamentSettings = OrnamentSettings()
     var debugOptions: MapViewDebugOptions = [.camera]
     var performance = PerformanceSettings()
+    var isCullingShapeEnabled = true
 
     struct OrnamentSettings {
         var isScaleBarVisible = true
@@ -25,6 +26,18 @@ struct Settings {
             PerformanceStatisticsOptions(samplerOptions, samplingDurationMillis: Double(samplingDurationMillis))
         }
     }
+
+    fileprivate var cullingShape: [CGPoint] {
+        guard isCullingShapeEnabled else { return [] }
+        return [
+            CGPoint(x: 0.35, y: 0.37),  // top-left
+            CGPoint(x: 0.65, y: 0.37),  // top-right
+            CGPoint(x: 0.85, y: 0.50),  // right
+            CGPoint(x: 0.65, y: 0.63),  // bottom-right
+            CGPoint(x: 0.35, y: 0.63),  // bottom-left
+            CGPoint(x: 0.15, y: 0.50)   // left
+        ]
+    }
 }
 
 struct MapSettingsExample: View {
@@ -49,6 +62,7 @@ struct MapSettingsExample: View {
                     compass: CompassViewOptions(visibility: settings.ornamentSettings.isCompassVisible ? .visible : .hidden)
                 ))
                 .debugOptions(settings.debugOptions)
+                .screenCullingShape(settings.cullingShape)
                 .ignoresSafeArea()
                 .sheet(isPresented: $settingsOpened) {
                     SettingsView(settings: $settings)
@@ -70,6 +84,30 @@ struct MapSettingsExample: View {
                 }
                 .floating()
             }
+
+            if settings.isCullingShapeEnabled {
+                ZStack {
+                    Color.black.opacity(0.7)
+                        .compositingGroup()
+                        .overlay {
+                            ZStack {
+                                // cutout
+                                HexagonShape(points: settings.cullingShape)
+                                    .fill()
+                                    .blendMode(.destinationOut)
+
+                                // border
+                                HexagonShape(points: settings.cullingShape)
+                                    .stroke(.white, lineWidth: 4)
+                                    .shadow(color: .white, radius: 5)
+                            }
+
+                        }
+                }
+                .ignoresSafeArea()
+                .allowsHitTesting(false)
+                .compositingGroup()
+            }
         }
     }
 
@@ -148,6 +186,13 @@ struct SettingsView: View {
             } header: {
                 Text("Debug Options")
             }
+
+            Section {
+                Toggle("Simulate hex screen shape", isOn: $settings.isCullingShapeEnabled)
+            } header: {
+                Text("Screen culling shape")
+            }
+
             Section {
                 let samplerOptions = [
                     ("Per Frame", PerformanceStatisticsOptions.SamplerOptions.perFrame),
@@ -173,6 +218,23 @@ struct SettingsView: View {
     }
 }
 
+struct HexagonShape: Shape {
+    let points: [CGPoint]
+
+    func path(in rect: CGRect) -> Path {
+        let scaledPoints = points.map { CGPoint(x: $0.x * rect.width, y: $0.y * rect.height) }
+
+        var path = Path()
+        path.move(to: scaledPoints[0])
+        for point in scaledPoints.dropFirst() {
+            path.addLine(to: point)
+        }
+        path.closeSubpath()
+
+        return path
+    }
+}
+
 private extension Binding where Value: OptionSet {
     func contains(option: Value.Element) -> Binding<Bool> {
         Binding<Bool> {

Sources/MapboxMaps/Foundation/MapboxMap.swift

@@ -78,6 +78,7 @@ protocol MapboxMapProtocol: AnyObject {
         stateKey: T.StateKey?,
         callback: ((Error?) -> Void)?
     ) -> Cancelable
+    var screenCullingShape: [CGPoint] { get set }
 }
 
 // swiftlint:disable type_body_length

Sources/MapboxMaps/SwiftUI/Deps.swift

@@ -21,6 +21,7 @@ struct MapDependencies {
     var viewportOptions = ViewportOptions(transitionsToIdleUponUserInteraction: true, usesSafeAreaInsetsAsPadding: true)
     var performanceStatisticsParameters: Map.PerformanceStatisticsParameters?
     var attributionMenuFilter: ((AttributionMenuItem) -> Bool)?
+    var screenCullingShape = [CGPoint]()
 
     var onMapTap: ((InteractionContext) -> Void)?
     var onMapLongPress: ((InteractionContext) -> Void)?

Sources/MapboxMaps/SwiftUI/Map.swift

@@ -369,6 +369,16 @@ public extension Map {
         copy.mapDependencies.additionalSafeArea.updateEdges(edges, length)
         return copy
     }
+
+    /// 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)
+    func screenCullingShape(_ shape: [CGPoint]) -> Self {
+        copyAssigned(self, \.mapDependencies.screenCullingShape, shape)
+    }
 }
 
 extension Map {

Sources/MapboxMaps/SwiftUI/MapBasicCoordinator.swift

@@ -95,6 +95,7 @@ final class MapBasicCoordinator {
         assign(&mapView, \.frameRate, value: deps.frameRate)
         assign(&mapView, \.presentationTransactionMode, value: deps.presentationTransactionMode)
         assign(&mapView, \.viewportManager.options, value: deps.viewportOptions)
+        assign(mapboxMap.screenCullingShape, { mapboxMap.screenCullingShape = $0 }, value: deps.screenCullingShape)
 
         cameraChangeHandlers = deps.cameraChangeHandlers
         mapView.gestureManager.gestureHandlers = deps.gestureHandlers

Tests/MapboxMapsTests/Foundation/Mocks/MockMapboxMap.swift

@@ -44,6 +44,9 @@ final class MockMapboxMap: MapboxMapProtocol {
 
     var anchor = CGPoint.zero
 
+    @Stubbed
+    var screenCullingShape: [CGPoint] = []
+
     let setCameraStub = Stub<MapboxMaps.CameraOptions, Void>()
     func setCamera(to cameraOptions: MapboxMaps.CameraOptions) {
         setCameraStub.call(with: cameraOptions)

Tests/MapboxMapsTests/SwiftUI/MapBasicCoordinatorTests.swift

@@ -54,18 +54,22 @@ final class MapBasicCoordinatorTests: XCTestCase {
         XCTAssertEqual(mapboxMap.northOrientationStub.invocations.count, 0)
         XCTAssertEqual(mapboxMap.setConstraintModeStub.invocations.count, 0)
         XCTAssertEqual(mapboxMap.setViewportModeStub.invocations.count, 0)
+        XCTAssertEqual(mapboxMap.screenCullingShape, [])
 
         update(with: MapDependencies(
             constrainMode: .none,
             viewportMode: .flippedY,
-            orientation: .downwards))
+            orientation: .downwards,
+            screenCullingShape: [.init(x: 1, y: 2)]))
         XCTAssertEqual(mapboxMap.setConstraintModeStub.invocations.count, 1)
         XCTAssertEqual(mapboxMap.setViewportModeStub.invocations.count, 1)
         XCTAssertEqual(mapboxMap.northOrientationStub.invocations.count, 1)
+        XCTAssertEqual(mapboxMap.$screenCullingShape.setStub.invocations.count, 1)
 
         XCTAssertEqual(mapboxMap.setConstraintModeStub.invocations.first?.parameters, ConstrainMode.none)
         XCTAssertEqual(mapboxMap.setViewportModeStub.invocations.first?.parameters, .flippedY)
         XCTAssertEqual(mapboxMap.northOrientationStub.invocations.first?.parameters, .downwards)
+        XCTAssertEqual(mapboxMap.$screenCullingShape.setStub.invocations.first?.parameters, [CGPoint(x: 1, y: 2)])
     }
 
     func testOrnamentOptions() {