Rename screen shape (#3377)

### 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 <[email protected]>
GitOrigin-RevId: 68a34816e8e5bacf61a119eb2503fc2cba59337c

Author: 2 people

CHANGELOG.md

@@ -5,6 +5,7 @@ Mapbox welcomes participation and contributions from everyone.
 # main
 ## Features ✨ and improvements 🏁
 * Expose `RenderThreadStatsRecorder` as experimental API. 
+* Expose an experimental API to define a non-rectangular screen culling shape(`MapboxMap.get/setScreenCullingShape`)
 
 
 # 11.12.0-rc.1

LICENSE.md

@@ -482,7 +482,7 @@ License: [The Apache Software License, Version 2.0](http://www.apache.org/licens
 
 ===========================================================================
 
-### MapboxCoreMaps,11.13.0-SNAPSHOT-04-23--04-29.git-3eea307,Mapbox ToS,Mapbox,https://www.mapbox.com/
+### MapboxCoreMaps,11.13.0-SNAPSHOT-04-23--05-20.git-ad48dc8,Mapbox ToS,Mapbox,https://www.mapbox.com/
 
 ```
 Mapbox Core Maps version 11.0

app/src/main/java/com/mapbox/maps/testapp/examples/DebugModeActivity.kt

@@ -1,9 +1,20 @@
 package com.mapbox.maps.testapp.examples
 
 import android.annotation.SuppressLint
+import android.content.Context
+import android.graphics.BlurMaskFilter
+import android.graphics.Canvas
+import android.graphics.Color
+import android.graphics.CornerPathEffect
+import android.graphics.Paint
+import android.graphics.Path
+import android.graphics.PorterDuff
+import android.graphics.PorterDuffXfermode
 import android.os.Bundle
 import android.view.Menu
 import android.view.MenuItem
+import android.view.View
+import android.view.ViewGroup
 import android.widget.TextView
 import androidx.appcompat.app.AppCompatActivity
 import com.google.android.material.snackbar.Snackbar
@@ -13,6 +24,7 @@ import com.mapbox.maps.MapboxMap
 import com.mapbox.maps.PerformanceSamplerOptions
 import com.mapbox.maps.PerformanceStatisticsOptions
 import com.mapbox.maps.Style
+import com.mapbox.maps.Vec2
 import com.mapbox.maps.debugoptions.MapViewDebugOptions
 import com.mapbox.maps.logE
 import com.mapbox.maps.logI
@@ -58,10 +70,40 @@ class DebugModeActivity : AppCompatActivity() {
 
     mapboxMap.loadStyle(Style.STANDARD)
     setupPerformanceStatisticsCollection()
+    setupScreenShapeButton()
     binding.mapView.compass.opacity = 0.5f
     binding.mapView.debugOptions = debugOptions
     registerListeners(mapboxMap)
   }
+  private var overlayView: HexSpotlightView? = null
+
+  private fun setupScreenShapeButton() {
+    binding.screenShapeButton.setOnClickListener {
+      when (binding.screenShapeButton.text) {
+        SCREEN_SHAPE_RECT -> {
+          binding.screenShapeButton.text = SCREEN_SHAPE_CUSTOM
+
+          mapboxMap.setScreenCullingShape(emptyList())
+          (overlayView?.parent as? ViewGroup)?.removeView(overlayView)
+        }
+        SCREEN_SHAPE_CUSTOM -> {
+          val shape = listOf(
+            Vec2(0.35, 0.34),
+            Vec2(0.65, 0.34),
+            Vec2(0.85, 0.50),
+            Vec2(0.65, 0.66),
+            Vec2(0.35, 0.66),
+            Vec2(0.15, 0.50)
+          )
+
+          overlayView = HexSpotlightView(this, shape)
+          addContentView(overlayView, ViewGroup.LayoutParams(ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT))
+          mapboxMap.setScreenCullingShape(shape)
+          binding.screenShapeButton.text = SCREEN_SHAPE_RECT
+        }
+      }
+    }
+  }
 
   private fun setupPerformanceStatisticsCollection() {
     binding.perfStatButton.setOnClickListener {
@@ -229,5 +271,71 @@ class DebugModeActivity : AppCompatActivity() {
     private const val TAG_PERFORMANCE_STATISTICS = "PerformanceStatistics"
     private const val PERF_STAT_STOP_COLLECT_BUTTON = "Stop collecting"
     private const val PERF_STAT_START_COLLECT_BUTTON = "Collect Perf Stats"
+    private const val SCREEN_SHAPE_CUSTOM = "Hex screen"
+    private const val SCREEN_SHAPE_RECT = "Rect screen"
+  }
+}
+
+@SuppressLint("ViewConstructor")
+class HexSpotlightView(context: Context, private val shape: List<Vec2>) : View(context) {
+
+  private val overlayPaint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
+    color = Color.parseColor("#80000000") // dimmed background
+  }
+
+  private val clearPaint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
+    xfermode = PorterDuffXfermode(PorterDuff.Mode.CLEAR)
+  }
+
+  private val strokePaint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
+    color = Color.WHITE
+    style = Paint.Style.STROKE
+    strokeWidth = 4F * context.resources.displayMetrics.density
+    strokeJoin = Paint.Join.ROUND
+    pathEffect = CornerPathEffect(12F * context.resources.displayMetrics.density)
+  }
+  private var hexPath: Path = createPath(width.toFloat(), height.toFloat())
+
+  private val glowPaint = Paint(Paint.ANTI_ALIAS_FLAG).apply {
+    color = Color.WHITE
+    style = Paint.Style.STROKE
+    strokeWidth = 4F * context.resources.displayMetrics.density
+    maskFilter = BlurMaskFilter(32F, BlurMaskFilter.Blur.OUTER)
+    strokeJoin = Paint.Join.ROUND
+    pathEffect = CornerPathEffect(12F * context.resources.displayMetrics.density)
+  }
+
+  override fun onLayout(changed: Boolean, left: Int, top: Int, right: Int, bottom: Int) {
+    super.onLayout(changed, left, top, right, bottom)
+
+    hexPath = createPath(width.toFloat(), height.toFloat())
+  }
+
+  override fun onDraw(canvas: Canvas) {
+    super.onDraw(canvas)
+
+    val layer = canvas.saveLayer(null, null)
+
+    // Draw full dim overlay
+    canvas.drawRect(0f, 0f, width.toFloat(), height.toFloat(), overlayPaint)
+
+    // Draw hexagon cutout
+    canvas.drawPath(hexPath, clearPaint)
+    canvas.drawPath(hexPath, glowPaint)
+    canvas.drawPath(hexPath, glowPaint)
+    canvas.drawPath(hexPath, strokePaint)
+
+    canvas.restoreToCount(layer)
+  }
+
+  private fun createPath(w: Float, h: Float): Path {
+    val path = Path()
+    shape.forEachIndexed { index, pt ->
+      val x = pt.x * w
+      val y = pt.y * h
+      if (index == 0) path.moveTo(x.toFloat(), y.toFloat()) else path.lineTo(x.toFloat(), y.toFloat())
+    }
+    path.close()
+    return path
   }
 }

app/src/main/res/layout/activity_debug.xml

@@ -51,4 +51,17 @@
         app:layout_constraintBottom_toBottomOf="parent"
         tools:ignore="HardcodedText" />
 
+    <Button
+        android:id="@+id/screenShapeButton"
+        android:layout_width="wrap_content"
+        android:layout_height="wrap_content"
+        android:padding="10dp"
+        android:textSize="18sp"
+        android:text="Hex screen"
+        android:layout_marginEnd="12dp"
+        android:layout_marginBottom="12dp"
+        app:layout_constraintEnd_toEndOf="parent"
+        app:layout_constraintBottom_toBottomOf="parent"
+        tools:ignore="HardcodedText" />
+
 </androidx.constraintlayout.widget.ConstraintLayout>

gradle/libs.versions.toml

@@ -35,8 +35,8 @@ japicmp = "0.4.1"
 # Dependencies
 
 # GlNative and Common are used by the convention plugin
-mapboxGlNative = "11.13.0-SNAPSHOT-04-23--04-29.git-3eea307"
-mapboxCommon = "24.13.0-SNAPSHOT-04-23--04-29.git-3eea307"
+mapboxGlNative = "11.13.0-SNAPSHOT-04-23--05-20.git-ad48dc8"
+mapboxCommon = "24.13.0-SNAPSHOT-04-23--05-20.git-ad48dc8"
 
 mapboxBase = "0.11.0"
 mapboxGestures = "0.8.0"

maps-sdk/api/Release/metalava.txt

@@ -226,6 +226,7 @@ package com.mapbox.maps {
     method @RestrictTo(androidx.annotation.RestrictTo.Scope.LIBRARY_GROUP_PREFIX) @com.mapbox.maps.MapboxDelicateApi @com.mapbox.maps.MapboxExperimental public com.mapbox.maps.Map getNativeMap();
     method public byte getPrefetchZoomDelta();
     method public boolean getRenderWorldCopies();
+    method @com.mapbox.maps.MapboxExperimental public java.util.List<com.mapbox.maps.Vec2> getScreenCullingShape();
     method public com.mapbox.maps.Size getSize();
     method public com.mapbox.maps.Style? getStyle();
     method public void getStyle(com.mapbox.maps.Style.OnStyleLoaded onStyleLoaded);
@@ -315,6 +316,7 @@ package com.mapbox.maps {
     method public void setNorthOrientation(com.mapbox.maps.NorthOrientation northOrientation);
     method public void setPrefetchZoomDelta(byte delta);
     method public void setRenderWorldCopies(boolean renderWorldCopies);
+    method @com.mapbox.maps.MapboxExperimental public void setScreenCullingShape(java.util.List<com.mapbox.maps.Vec2> shape);
     method public void setTileCacheBudget(com.mapbox.maps.TileCacheBudget? tileCacheBudget);
     method public void setUserAnimationInProgress(boolean inProgress);
     method public void setViewportMode(com.mapbox.maps.ViewportMode viewportMode);

maps-sdk/api/maps-sdk.api

@@ -226,6 +226,7 @@ public final class com/mapbox/maps/MapboxMap : com/mapbox/maps/MapboxStyleManage
 	public final fun getNativeMap ()Lcom/mapbox/maps/Map;
 	public final fun getPrefetchZoomDelta ()B
 	public final fun getRenderWorldCopies ()Z
+	public final fun getScreenCullingShape ()Ljava/util/List;
 	public fun getSize ()Lcom/mapbox/maps/Size;
 	public final fun getStyle ()Lcom/mapbox/maps/Style;
 	public final fun getStyle (Lcom/mapbox/maps/Style$OnStyleLoaded;)V
@@ -314,6 +315,7 @@ public final class com/mapbox/maps/MapboxMap : com/mapbox/maps/MapboxStyleManage
 	public fun setNorthOrientation (Lcom/mapbox/maps/NorthOrientation;)V
 	public final fun setPrefetchZoomDelta (B)V
 	public final fun setRenderWorldCopies (Z)V
+	public final fun setScreenCullingShape (Ljava/util/List;)V
 	public final fun setTileCacheBudget (Lcom/mapbox/maps/TileCacheBudget;)V
 	public fun setUserAnimationInProgress (Z)V
 	public fun setViewportMode (Lcom/mapbox/maps/ViewportMode;)V

maps-sdk/src/main/java/com/mapbox/maps/MapboxMap.kt

@@ -2323,6 +2323,35 @@ class MapboxMap :
     return nativeMap.getRenderWorldCopies()
   }
 
+  /**
+   * 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.
+   *
+   * @param shape shape of the screen
+   *
+   */
+  @MapboxExperimental
+  fun setScreenCullingShape(shape: List<Vec2>) {
+    checkNativeMap("setScreenCullingShape")
+    return nativeMap.setScreenCullingShape(shape)
+  }
+
+  /**
+   * A convex polygon that describes the shape of the screen in case it is non-rectangular.
+   * Every screen-coordinate is in 0 to 1 range, with (0, 0) being top-left and (1, 1) 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.
+   *
+   * @return shape of the screen
+   */
+  @MapboxExperimental
+  fun getScreenCullingShape(): List<Vec2> {
+    checkNativeMap("getScreenCullingShape")
+    return nativeMap.getScreenCullingShape()
+  }
+
   /**
    * Enable real-time collection of map rendering performance statistics, for development purposes. Use after `render()` has
    * been called for the first time.

maps-sdk/src/main/java/com/mapbox/maps/NativeMapImpl.kt

@@ -706,6 +706,14 @@ internal class NativeMapImpl(val map: Map) {
     return map.centerAltitudeMode
   }
 
+  fun setScreenCullingShape(shape: List<Vec2>) {
+    map.screenCullingShape = shape
+  }
+
+  fun getScreenCullingShape(): List<Vec2> {
+    return map.screenCullingShape
+  }
+
   fun startPerformanceStatisticsCollection(
     options: PerformanceStatisticsOptions,
     callback: PerformanceStatisticsCallback,

maps-sdk/src/test/java/com/mapbox/maps/MapboxMapTest.kt

@@ -1887,6 +1887,19 @@ class PixelForCoordinatesTest(
     assertEquals(expected, screenCoordinates)
   }
 
+  @Test
+  fun getScreenCullingShape() {
+    mapboxMap.getScreenCullingShape()
+    verify { nativeMap.getScreenCullingShape() }
+  }
+
+  @Test
+  fun setScreenShape() {
+    val shape = mockk<List<Vec2>>()
+    mapboxMap.setScreenCullingShape(shape)
+    verify { nativeMap.setScreenCullingShape(shape) }
+  }
+
   @After
   fun cleanUp() {
     unmockkStatic(Map::class)