MapboxMapController

Shared constants for MapboxMapController: logging tag, camera projection modes, and GL-stencil ids.

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.

Mapbox map handle; non-null after construction. Safe to use from the main thread once the view is attached.

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.

instance used for managing animation and time-based data.

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.

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 a LayerCode preset (source + descriptor + paint from service).

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.

Removes the custom stencil/texture mask from layerId so weather draws unmasked. Mask vector layers (motorway, CONUS fill) stay on the map and can be re-enabled via reregisterCustomStencilMask after restoring TileLayer.stencilLayerMask.

Clears all pending-download bookkeeping across every EncodedTileLayer and the shared Timeline load-session state (pending tile lists, download-progress counters, and the downloading/waiting flags). Use to force-recover a controller stuck reporting outstanding downloads that will never resolve (e.g. after a watchdog timeout).

Activates GLES hybrid land ∩ line stencil on a weather layer (marine clip + motorways on land). Call after addWeatherLayer when the layer uses MaskLayerKind.LAND plus line-only com.xweather.mapsgl.layers.spec.StencilLayerMaskSpec refs.

Re-binds OSM stencil fetch, tile-cache replay, and per-layer render hooks after addWeatherLayer with a built-in MaskLayerKind. Call from app demos when switching mask types across activities (land → water).

Formats a Date as an ISO-8601-like UTC string (first 19 chars + Z) for display or logging.

Visible geographic bounds derived from Mapbox unwrapped camera bounds and VisibleGeoBounds.

Resolves the WeatherConfiguration that would be used for addWeatherLayer with this layerCode.

Returns the map camera's current field-of-view in degrees.

Returns the map's container size.

Raw unwrapped longitudes from Mapbox — not passed through VisibleGeoBounds, which can collapse the viewport to a single -180,180 strip and hide extra world copies for encoded tile draws.

Returns A layer given its LayerCode.

Returns whether the map currently contains a data source with the specified identifier.

Returns whether the map currently contains a weather layer with the specified identifier.

Reorders a style layer in the Mapbox style stack.

Removes a previously registered callback for name.

Registers callback for controller-issued events named name (see MapControllerEvents).

ComponentCallbacks2: no-op; orientation is handled via camera callbacks.

DefaultLifecycleObserver callback: begins observing raster tile API events for owner's lifetime. Invoked automatically once registerMapLifecycleObserver has attached this controller.

LifecycleOwner destroy hook: delegates to shutdown.

ComponentCallbacks2: no-op; deprecated in favor of onTrimMemory.

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.

LifecycleOwner stop hook: cancels the pending move-end debounce and drops any queued GL-stencil OSM prefetch work before delegating to MapController.onStop.

TileLayer.TileLayerEventListener hook; reserved for future tile-layer events from Mapbox path.

Clears encoded tile caches outside the visible viewport when the OS reports memory pressure (ComponentCallbacks2); aggressive only for background / UI-hidden levels.

Triggers a manual pre-fetch of tile animation data.

Queries encoded tile layers and Mapbox vector layers at point for the given layer ids.

Mapbox queryRenderedFeatures at a screen point for the given vector layers; fills data-inspector vector fields when onTouch matches the active inspector buffer.

Queries features within a rectangular area.

Legacy vector query implementation kept for compatibility; prefer queryFeatures.

Refresh the custom stencil mask for the weather layer layerId after a mask vector layer's paint has been mutated in place (e.g. new line thickness / cap / join). Updates the coordinator's per-tile listeners so subsequent mesh builds use the new paint, replays cached MVT features through the new listeners so already-loaded tiles rebuild their stencil meshes, and asks Mapbox for a repaint.

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.

Rebinds MVT/GeoJSON stencil listeners after TileLayer.stencilLayerMask.layers changes (e.g. toggling individual mask layers in Demo 3). Paint-only updates should use refreshCustomStencilMask instead.

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).

Queues GL-stencil mesh prefetch for the weather tile coords currently being rendered under maskKind (and countryIso3166Alpha2 for MaskLayerKind.COUNTRY), then kicks off runGlStencilPrefetchWorker. Tiles that already have a renderable mesh are skipped unless a transportation zoom-bin change forces a visible-tile refresh at the new stroke width.

Unconditionally queues coords as GL-stencil OSM prefetch keys for a custom stencil mask (no existing-mesh check, unlike schedulePrefetchGlStencilMaskTilesForWeatherRender) and kicks off runGlStencilPrefetchWorker.

Sets map bearing (rotation in degrees; 0 = north up).

Moves the camera center while preserving the current getZoom.

Marks the custom MapboxLayerHost for layerId as needing its GL textures rebound.

Syncs MapsGL layer visibility, custom layer host visibility, and Mapbox style visibility for id.

Sets a paint-related property on a layer (reserved for future Mapbox style parity; not fully implemented).

Sets map pitch / tilt in degrees.

Shows or hides every map layer (and optional legend) belonging to code, including composite children.

Animates or jumps the camera to the given Mapbox zoom.

Tears down this controller: cancels pending jobs, clears GL-stencil prefetch bookkeeping, cancels all Mapbox subscriptions (mapboxCancelables), removes the GL-stencil base OSM fetch layer, and clears MapController.layerHosts. Safe to call more than once.

Dispatches a named event to listeners registered with on for type.

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.