MapsGL Android - Map Controller

A map controller acts as an adapter to a third-party mapping library and provides a consistent interface between the functionality of MapsGL and the underlying map. All MapsGL-related data — sources, weather layers, custom layers, and the animation timeline — is managed by the map controller.

Supported Mapping Libraries

MapsGL SDK for Android currently supports integration with the following third-party mapping libraries:

Read more about setting up a map controller with Mapbox.

Example

The following example creates a Mapbox map instance and initializes a MapsGL MapboxMapController with the map:

val xweatherAccount = XweatherAccount(
    getString(R.string.xweather_client_id),
    getString(R.string.xweather_client_secret)
)
 
val mapLoadedCallback = MapLoadedCallback {
    mapController.addWeatherLayer(LayerCode.TEMPERATURES)
}
 
binding.mapView.viewTreeObserver.addOnGlobalLayoutListener(object : ViewTreeObserver.OnGlobalLayoutListener {
    override fun onGlobalLayout() {
        binding.mapView.viewTreeObserver.removeOnGlobalLayoutListener(this)
 
        mapController = MapboxMapController(mapView, xweatherAccount)
 
        with(mapController) {
            mapboxMap?.setProjection(projection(ProjectionName.MERCATOR))
            mapboxMap?.subscribeMapLoaded(mapLoadedCallback)
        }
    }
})

Refer to the MapController API reference for available properties and methods.

Registering Custom Images

If you need a custom image for symbol-based styling — for example a custom icon on a GridLayerDescriptor — register it on the Mapbox style before adding the layer. MapsGL then references that style image id from IconPaint.image:

val image = BitmapFactory.decodeResource(resources, R.drawable.my_grid_icon)
mapController.mapboxMap?.getStyle { style ->
    style.addImage("my-grid-icon", image, false)
}

Pass true as the third argument when the bitmap is an SDF (signed-distance field) icon so the renderer can tint and scale it.

You can then reference the registered image id from your layer paint:

val layer = GridLayerDescriptor(
    id = "custom-grid",
    source = source.id,
    paint = GridLayerPaint(
        icon = IconPaint(
            image = StyleValue.Constant("my-grid-icon"),
            iconSize = IconSize(width = 24f, height = 24f),
        ),
    ),
)
controller.addLayer(layer, beforeID = null)

Built-in weather layers load their sprite sheets automatically. You only need to register an image when you supply your own icon id.