Globe CustomLayer Example and API (#4843)

https://mapbox.atlassian.net/browse/MAPSAND-2177
Android platform version of
mapbox/mapbox-sdk#3860

https://github.com/user-attachments/assets/43a4018c-890a-4690-8619-f5e88082ec4b

cc @mapbox/maps-android

GitOrigin-RevId: df3eb33f8cfc6fd91c9350f95813deecf0aacf18

Author: kediarov

app/src/main/AndroidManifest.xml

@@ -875,6 +875,18 @@
                 android:name="android.support.PARENT_ACTIVITY"
                 android:value=".ExampleOverviewActivity" />
         </activity>
+        <activity
+            android:name=".examples.customlayer.globe.GlobeCustomLayerActivity"
+            android:description="@string/description_globe_custom_layer"
+            android:exported="true"
+            android:label="@string/activity_globe_custom_layer">
+            <meta-data
+                android:name="@string/category"
+                android:value="@string/category_custom_layer" />
+            <meta-data
+                android:name="android.support.PARENT_ACTIVITY"
+                android:value=".ExampleOverviewActivity" />
+        </activity>
         <activity
             android:name=".examples.TransparentBackgroundActivity"
             android:description="@string/description_transparent_bg"

app/src/main/java/com/mapbox/maps/testapp/examples/customlayer/globe/Cube.kt

@@ -0,0 +1,50 @@
+package com.mapbox.maps.testapp.examples.customlayer.globe
+
+import com.mapbox.geojson.Point
+import com.mapbox.maps.Projection
+import com.mapbox.maps.Vec3
+
+/**
+ * Creates data and vertices for a cube in ECEF coordinates
+ * */
+class Cube(
+  val location: Point,
+  val sizeMeters: Float,
+  val altitudeMeters: Float,
+  colors: IntArray,
+  mesh: CubeMesh,
+) {
+
+  private val _ecefVertices = ArrayList<Vec3>(mesh.vertices.size)
+  val ecefVertices: List<Vec3> get() = _ecefVertices
+
+  // NxN grid, of quads.
+  private val _colorVertices = ArrayList<Int>(mesh.verticesPerCubeSide * colors.size)
+  val colorVertices: List<Int> get() = _colorVertices
+
+  init {
+    // normalized to [0, 1]
+    val positionMercator = Projection.latLngToMercatorXY(location)
+    val metersToMercator = metersToMercator(location.latitude())
+    for (vertex in mesh.vertices) {
+      val x = positionMercator.x + vertex.x * sizeMeters * metersToMercator
+      val y = positionMercator.y + vertex.y * sizeMeters * metersToMercator
+      val altitude = vertex.z * sizeMeters + altitudeMeters
+
+      val vertexEcef = toEcef(
+        latitude = latFromMercatorY(y),
+        longitude = lngFromMercatorX(x),
+        altitude,
+      )
+
+      _ecefVertices.add(vertexEcef)
+    }
+
+    // Create vertex buffer for cube side colors
+    for (color in colors) {
+      repeat(mesh.verticesPerCubeSide) {
+        _colorVertices.add(color)
+      }
+    }
+  }
+}

app/src/main/java/com/mapbox/maps/testapp/examples/customlayer/globe/CubeMesh.kt

@@ -0,0 +1,56 @@
+package com.mapbox.maps.testapp.examples.customlayer.globe
+
+import com.mapbox.maps.Vec3
+import kotlin.math.max
+
+/**
+ * Create a static cube mesh to be rendered with a transformation matrix.
+ * It defines vertices in OpenGL local space [-1.0; 1.0]
+ * */
+class CubeMesh(
+  tessellation: Int = 1,
+) {
+
+  val tessellation = max(tessellation, 1)
+  val verticesPerCubeSide = tessellation * tessellation * 6
+  val vertices = ArrayList<Vec3>(sides.size * this.tessellation * this.tessellation)
+
+  init {
+    val step = 1.0 / this.tessellation
+    for (side in sides) {
+      // Create vertices for the side
+      repeat(this.tessellation) { y ->
+        repeat(this.tessellation) { x ->
+          val topLeft =
+            side.topLeft + side.right * step * x.toDouble() + side.down * step * y.toDouble()
+          val v00 = topLeft
+          val v10 = topLeft + side.right * step
+          val v11 = topLeft + side.right * step + side.down * step
+          val v01 = topLeft + side.down * step
+
+          vertices.add(v00)
+          vertices.add(v10)
+          vertices.add(v11)
+
+          vertices.add(v11)
+          vertices.add(v01)
+          vertices.add(v00)
+        }
+      }
+    }
+  }
+
+  companion object {
+
+    private val sides = arrayOf(
+      Side(Vec3(-0.5, 0.5, 0.5), Vec3(1.0, 0.0, 0.0), Vec3(0.0, -1.0, 0.0)),
+      Side(Vec3(0.5, 0.5, 0.5), Vec3(0.0, 0.0, -1.0), Vec3(0.0, -1.0, 0.0)),
+      Side(Vec3(0.5, 0.5, -0.5), Vec3(-1.0, 0.0, 0.0), Vec3(0.0, -1.0, 0.0)),
+      Side(Vec3(-0.5, 0.5, -0.5), Vec3(0.0, 0.0, 1.0), Vec3(0.0, -1.0, 0.0)),
+      Side(Vec3(-0.5, 0.5, -0.5), Vec3(1.0, 0.0, 0.0), Vec3(0.0, 0.0, 1.0)),
+      Side(Vec3(-0.5, -0.5, 0.5), Vec3(1.0, 0.0, 0.0), Vec3(0.0, 0.0, -1.0)),
+    )
+
+    private data class Side(val topLeft: Vec3, val right: Vec3, val down: Vec3)
+  }
+}

app/src/main/java/com/mapbox/maps/testapp/examples/customlayer/globe/GlobeCustomLayerActivity.kt

@@ -0,0 +1,80 @@
+package com.mapbox.maps.testapp.examples.customlayer.globe
+
+import android.os.Bundle
+import androidx.appcompat.app.AppCompatActivity
+import com.mapbox.geojson.Point
+import com.mapbox.maps.CameraOptions
+import com.mapbox.maps.Style
+import com.mapbox.maps.extension.style.layers.CustomLayer
+import com.mapbox.maps.extension.style.layers.addLayer
+import com.mapbox.maps.extension.style.layers.customLayer
+import com.mapbox.maps.extension.style.layers.properties.generated.ProjectionName
+import com.mapbox.maps.extension.style.projection.generated.projection
+import com.mapbox.maps.extension.style.style
+import com.mapbox.maps.testapp.R
+import com.mapbox.maps.testapp.databinding.ActivityGlobeCustomLayerBinding
+
+/**
+ * Test activity showcasing the Custom Layer API in globe projection.
+ * */
+class GlobeCustomLayerActivity : AppCompatActivity() {
+
+  private var _binding: ActivityGlobeCustomLayerBinding? = null
+  private val binding get() = _binding!!
+  private val mapboxMap get() = binding.mapView.mapboxMap
+  private var _host: GlobeCustomLayerHost? = null
+  private val host: GlobeCustomLayerHost get() = _host!!
+
+  override fun onCreate(savedInstanceState: Bundle?) {
+    super.onCreate(savedInstanceState)
+    _binding = ActivityGlobeCustomLayerBinding.inflate(layoutInflater)
+    setContentView(binding.root)
+    val repaint = Runnable(mapboxMap::triggerRepaint)
+    _host = GlobeCustomLayerHost {
+      binding.mapView.post(repaint)
+    }
+    mapboxMap.loadStyle(
+      style(Style.STANDARD) {
+        +customLayer(
+          layerId = CUSTOM_LAYER_ID,
+          host = host
+        )
+        +projection(ProjectionName.GLOBE)
+      }
+    ) {
+      mapboxMap.setCamera(CAMERA)
+      binding.fabSwapVisibility.setOnClickListener {
+        swapCustomLayer()
+      }
+    }
+  }
+
+  override fun onDestroy() {
+    super.onDestroy()
+    _binding = null
+    _host = null
+  }
+
+  private fun addCustomLayer(style: Style) {
+    style.addLayer(
+      CustomLayer(CUSTOM_LAYER_ID, host),
+    )
+    binding.fabSwapVisibility.setImageResource(R.drawable.ic_layers_clear)
+  }
+
+  private fun swapCustomLayer() {
+    val style = mapboxMap.style ?: return
+    if (style.styleLayerExists(CUSTOM_LAYER_ID)) {
+      style.removeStyleLayer(CUSTOM_LAYER_ID)
+      binding.fabSwapVisibility.setImageResource(R.drawable.ic_layers)
+    } else {
+      addCustomLayer(style)
+    }
+  }
+
+  companion object {
+    private const val CUSTOM_LAYER_ID = "customId"
+    private val CAMERA =
+      CameraOptions.Builder().center(Point.fromLngLat(20.0, 58.0)).pitch(0.0).zoom(1.0).build()
+  }
+}