Map
Bridge between the host map view (Mapbox MapView) and MapsGL: sources, tile layers, timeline, data inspector, legends, and weather APIs.
Use com.xweather.mapsgl.map.mapbox.MapboxMapController as the concrete implementation for Mapbox.
Parameters
Host MapView; used for context, lifecycle, and dimensions.
Xweather credentials used by service and tile requests.
Inheritors
Properties
Configuration options that control the behavior of timeline animations and data preloading.
Geographic center of the map in latitude/longitude degrees, kept in sync with the camera.
Pick/inspect weather values at a tap location; enable with addDataInspectorControl. Configure off-screen dismissal via DataInspectorControl.cancelCalloutWhenOffScreen.
Internal debounce job for camera move-end handling; managed by MapboxMapController.
Approximate download progress fraction (0f–1f) while tiles are in flight.
All MapsGL map layers currently registered on this controller, keyed by layer id.
Optional UI control for layer legends; install with add.
Session id assigned at construction; must match Timeline.mapSessionId for global tile bookkeeping (com.xweather.mapsgl.data.TileList) to apply to this controller.
Observes encoded-tile metadata keys; when a layer id is emitted, that TileLayer refreshes visible tiles. Attach only if you extend encoded sources; normally the controller wires this internally.
Posted when the current load session completes (encoded downloads and bind pipeline idle).
Emits MapLoadProgress while map data loads. Use onLoadProgress.observe(this) { progress -> ... } like other LiveData on this controller. For coroutine / flow access, see onLoadProgressValue.
Same progress as onLoadProgress, exposed as a Signal for coroutine collectors.
Posted when loading begins for any tracked data source (e.g. tile wave started).
Fires with a source id after addSource registers it and the source is ready for layers.
The primary interface for communicating with the Xweather backend.
Self-reference to this controller instance, used to disambiguate this inside nested listener/Runnable bodies (e.g. downloadTrackingRunnable) where this would otherwise refer to the inner object rather than the MapController.
When true, custom com.xweather.mapsgl.layers.spec.StencilLayerMaskSpec masks are baked once per dirty frame into an R8 viewport texture (JS tMask) instead of per-tile stencil rewrites during weather draw.
Library-internal: at least one visible layer is waiting on tile data.
Library-internal: edge detection for post-download refresh.
Library-internal: previous frame had pending tile downloads.
Functions
Installs the provided legend control, wiring it to map events and populating initial legends.
Hook for map SDK–specific registration of a custom layer host after MapsGL created the layer.
Activates and initializes the Data Inspector control for the map.
Adds a new layer to the map.
Adds or refreshes the legend defined on forConfig into the current legendControl.
Registers a data source. When the descriptor leaves ImageSourceDescriptor.authenticator / EncodedSourceDescriptor.authenticator / VectorSourceDescriptor.authenticator / GeoJSONSourceDescriptor.authenticator unset, this controller supplies service.authenticator automatically.
Adds a weather layer from an explicit WeatherConfiguration (use when you built the config from WeatherService factories instead of LayerCode).
Cancel scheduled mask-demo refresh work; call when the user picks another demo.
Returns the map's current rotational bearing in degrees, if supported. A bearing of 0 orients the map so that north is up.
Returns the map's geographical center coordinate.
Resolves the WeatherConfiguration that would be used for addWeatherLayer with this layerCode.
West/east longitude in degrees for tile enumeration (may lie outside -180, 180 when the camera shows several world copies). Defaults to getBounds; Mapbox uses raw unwrapped bounds so encoded layers can render every visible copy.
Returns A layer given its LayerCode.
Returns whether the map currently contains a weather layer with the specified identifier.
DefaultLifecycleObserver callback: begins observing raster tile API events for owner's lifetime. Invoked automatically once registerMapLifecycleObserver has attached this controller.
DefaultLifecycleObserver callback: tears down this controller when the host owner is destroyed. Delegates to shutdown; safe even if shutdown was already called explicitly.
Mapbox map click: forwards to the data inspector when it is enabled.
DefaultLifecycleObserver callback: resumes timeline playback, tile polling, and custom-layer updates when the host owner returns to the foreground. See resumeFromBackground.
DefaultLifecycleObserver callback: pauses timeline playback, tile polling, and custom-layer updates while the host owner is backgrounded. See pauseForBackground.
Triggers a manual pre-fetch of tile animation data.
Recomputes visible tiles for every visible MapsGL layer and marks custom layer hosts dirty.
Registers this controller with the MapView's lifecycle (Activity or fragment owner). Safe to call multiple times; typically invoked from MapboxMapController after attach.
Deactivates the Data Inspector control and cleans up its associated resources.
Removes a layer by id, detaches consumers, and cleans encoded-grid sidecars when present.
Removes the currently installed legend control and clears any associated observers.
Unregisters a data source from this controller (does not remove layers that still reference it).
Removes the weather layer(s) for code from the map, sources, legends, and mask sidecars as needed.
Custom StencilLayerMaskSpec / LayerMaskSpec demos need the Mapbox persistent custom layer, mask geometry, and encoded weather tiles before the first paint. Schedule after addWeatherLayer when the camera may still be moving (e.g. setCenter / setZoom).
Instanced gridded layers (wind arrows / barbs) need encoded tiles fetched after the Mapbox persistent custom layer exists. addToMap can call refreshVisibleLayers too early; schedule this from demo activities right after addWeatherLayer.
Land/water mask demos start paused; encoded preload must run only after the custom Mapbox layer exists and the camera has settled (fixes partial tiles on menu → demo re-entry).
When GLES stencil masking is on, ensures GlStencilOsm MVTs are loaded for the same tile grid as weather renderables (Mapbox's zero-opacity fetch layer does not always request every z/x/y).
Queues GlStencilOsm vector tile fetches for the same z/x/y grid as the encoded weather layer, without consulting built-in land/water/transport mesh caches. Used when masking is driven only by TileLayer.stencilLayerMask (EncodedTileLayer.glStencilMaskKind may be MaskLayerKind.NONE); without this, base-OSM MVTs for custom vector masks (e.g. Demo 3 motorways) load only on demand during draw, which makes panning feel choppy.
Sets the map's geographical center coordinate.
Marks the custom layer host for layerId so textures/uniforms are uploaded on the next draw pass.
Toggles visibility of a MapsGL layer by id and triggers a redraw.
Sets a paint-related property on a layer (reserved for future Mapbox style parity; not fully implemented).
Shows or hides every map layer (and optional legend) belonging to code, including composite children.
Tears down this controller's tile work, stencil registrations, and lifecycle observer. Demo activities call this from android.app.Activity.onStop so the next screen gets a fresh MapController instead of reusing stale Mapbox / timeline state.
Ensures the invisible Mapbox fetch layer for GlStencilOsm exists and seeds a small tile neighborhood. Call after adding a stencil-only motorway mask layer and before the weather layer.