Struct MapState 

pub struct MapState { /* private fields */ }

The central state object consumed by renderers each frame.

Owns the camera, layer stack, terrain manager, camera animator, and all per-frame derived data (zoom level, viewport bounds, frustum, mesh caches).

Field visibility

All fields are private. Use accessor methods for reads and targeted setters for writes:

Need	Method
Read camera	camera()
Set viewport size	set_viewport
Set camera target	set_camera_target
Set camera distance	set_camera_distance
Set camera pitch/yaw	set_camera_pitch, set_camera_yaw
Toggle projection	set_camera_mode
Set camera FOV	set_camera_fov_y
Read constraints	constraints()
Set max pitch	set_max_pitch
Add a layer	push_layer
Read layers	layers()
Read vector meshes	vector_meshes()
Read model instances	model_instances()
Dispatch input	handle_input
Animate camera	fly_to
Check animator	animator()
Replace terrain	set_terrain
Read terrain state	terrain()

Implementations

impl MapState

pub fn style_source_is_used(&self, source_id: &str) -> bool

Return true if the attached style currently uses the given source id.

pub fn style_layer_ids_using_source(&self, source_id: &str) -> Vec<&str>

Return the ordered style layer ids that currently reference the given source id.

pub fn reload_style_source( &mut self, source_id: impl Into<String>, source: StyleSource, ) -> Result<bool, StyleError>

Replace a source in the attached style document and re-apply the style.

pub fn clear_style_source( &mut self, source_id: &str, ) -> Result<Option<StyleSource>, StyleError>

Remove a source from the attached style document and re-apply the style.

impl MapState

pub fn pick(&self, query: PickQuery, options: PickOptions) -> PickResult

Execute a pick operation against the current map state.

pub fn pick_at_screen(&self, x: f64, y: f64, options: PickOptions) -> PickResult

Pick using logical screen-space coordinates relative to the viewport.

This is a convenience wrapper around Self::pick for the common cursor-driven interaction path used by hover and click handling.

pub fn pick_at_geo(&self, coord: GeoCoord, options: PickOptions) -> PickResult

Pick using a geographic coordinate.

This is a convenience wrapper around Self::pick for workflows that already resolved the target point in geospatial coordinates.

pub fn pick_along_ray( &self, origin: DVec3, direction: DVec3, options: PickOptions, ) -> PickResult

Pick along a world-space ray in the active scene projection.

This is a convenience wrapper around Self::pick for renderers or host integrations that already computed a world-space interaction ray.

pub fn query_rendered_features( &self, query: PickQuery, options: QueryOptions, ) -> Vec<QueriedFeature>

Query rendered vector features near the given query position.

pub fn query_rendered_features_at_screen( &self, x: f64, y: f64, options: QueryOptions, ) -> Vec<QueriedFeature>

Query rendered features at a logical screen-space coordinate.

This is the convenience wrapper for cursor-driven workflows that already operate in viewport pixel coordinates.

pub fn query_rendered_features_at_geo( &self, coord: GeoCoord, options: QueryOptions, ) -> Vec<QueriedFeature>

Query rendered features at a geographic coordinate.

This is the convenience wrapper for callers that already resolved the interaction point in geospatial coordinates.

pub fn query_rendered_features_along_ray( &self, origin: DVec3, direction: DVec3, options: QueryOptions, ) -> Vec<QueriedFeature>

Query rendered features along a world-space ray.

This is the convenience wrapper for renderer integrations that already computed a world-space interaction ray and want the standard rendered feature query behavior.

pub fn query_rendered_features_in_box( &self, x1: f64, y1: f64, x2: f64, y2: f64, options: QueryOptions, ) -> Vec<QueriedFeature>

Query rendered vector features whose geometry intersects a screen-space rectangle defined by two corner points.

The two corners are resolved to geographic coordinates via the current camera projection and then all visible features whose geometry overlaps the resulting bounding box are returned.

This is the Rustial equivalent of the Mapbox / MapLibre queryRenderedFeatures([sw, ne]) overload that accepts a bounding box instead of a single point.

Arguments

• x1, y1 – first corner in logical viewport pixels.
• x2, y2 – second corner in logical viewport pixels.
• options – layer/source filtering and tolerance controls.

Sorting

Results are sorted by layer-stack order (top-most layer first) and de-duplicated so the same feature is not returned twice from overlapping streamed tiles.

pub fn query_source_features( &self, source_id: &str, source_layer: Option<&str>, ) -> Vec<QueriedFeature>

Query currently loaded features for a style source.

impl MapState

pub fn update_terrain(&mut self)

Run just the terrain update (used by tests and manual pipelines).

impl MapState

pub fn new() -> Self

Create a new map state with default camera and no terrain.

pub fn with_terrain( terrain_config: TerrainConfig, terrain_cache_size: usize, ) -> Self

Create a map state with terrain support.

Arguments

• terrain_config – Terrain settings (enabled flag, mesh resolution, elevation source, vertical exaggeration, skirt depth).
• terrain_cache_size – Maximum number of elevation grids to keep in the LRU cache.

pub fn zoom_level(&self) -> u8

Current integer zoom level (0-22).

Derived from Camera::meters_per_pixel during update. Returns 0 before the first update.

pub fn fractional_zoom(&self) -> f64

Continuous fractional zoom level (e.g. 8.73).

Derived from Camera::near_meters_per_pixel using the same formula as zoom_level, but without rounding to an integer. Useful for debug displays and smooth zoom interpolation.

pub fn viewport_bounds(&self) -> &WorldBounds

Viewport bounding box in Web Mercator world space from the last update.

Includes an overscan margin for tile prefetching.

pub fn camera_velocity_config(&self) -> &CameraVelocityConfig

Read-only access to the camera-motion prediction configuration.

pub fn set_camera_velocity_config(&mut self, config: CameraVelocityConfig)

Replace the camera-motion prediction configuration.

pub fn camera_motion_state(&self) -> &CameraMotionState

Smoothed camera pan velocity and translated viewport prediction.

pub fn predicted_viewport_bounds(&self) -> &WorldBounds

Predicted viewport bounds after the configured look-ahead interval.

pub fn scene_viewport_bounds(&self) -> &WorldBounds

Viewport bounding box in the active planar scene projection.

pub fn frustum(&self) -> Option<&Frustum>

View frustum from the last update.

None only before the first update() call.

pub fn renderer_world_origin(&self) -> DVec3

Renderer/world origin used by the current render compatibility path.

This remains Web Mercator backed for the current raster/terrain stack, even when the camera itself uses a different planar projection.

pub fn scene_world_origin(&self) -> DVec3

Active scene origin in the camera’s currently selected planar projection.

Projection-specialized geometry paths such as terrain, vectors, symbols, models, and Bevy geo-entities should use this origin so their world coordinates remain aligned under non-Mercator planar projections.

pub fn terrain_meshes(&self) -> &[TerrainMeshData]

Terrain meshes produced during the last update.

Empty when terrain is disabled or no elevation data is cached.

pub fn hillshade_rasters(&self) -> &[PreparedHillshadeRaster]

Prepared DEM-derived hillshade rasters from the last update.

pub fn visible_tiles(&self) -> &[VisibleTile]

Visible tiles from the last update.

pub fn loading_placeholders(&self) -> &[LoadingPlaceholder]

Loading placeholders from the last update.

One entry per visible tile that has no data yet. Empty when all visible tiles are loaded.

pub fn placeholder_style(&self) -> &PlaceholderStyle

Active placeholder style.

pub fn set_placeholder_style(&mut self, style: PlaceholderStyle)

Replace the placeholder style.

pub fn coordinator_stats(&self) -> &CoordinatorStats

Read-only access to the cross-source tile request coordinator’s most recent diagnostics.

pub fn coordinator_config(&self) -> &CoordinatorConfig

Read-only access to the cross-source coordinator configuration.

pub fn set_coordinator_config(&mut self, config: CoordinatorConfig)

Replace the cross-source coordinator configuration.

Takes effect on the next frame. Set global_request_budget to 0 to disable coordination entirely.

pub fn set_prefetch_route(&mut self, route: Vec<GeoCoord>)

Set an optional navigation route for route-aware tile prefetch.

When set, the tile update loop will speculatively prefetch tiles along the route ahead of the current camera position, spending remaining speculative budget after viewport-prediction and zoom-direction prefetch.

The route should be a polyline of geographic coordinates ordered from origin to destination. Pass an empty slice or call clear_prefetch_route to disable.

pub fn clear_prefetch_route(&mut self)

Clear the navigation route used for route-aware tile prefetch.

pub fn prefetch_route(&self) -> Option<&[GeoCoord]>

Read-only access to the active prefetch route, if any.

pub fn tile_pipeline_diagnostics(&self) -> Option<TilePipelineDiagnostics>

Return a diagnostics snapshot for the first visible tile layer, if any.

pub fn tile_lifecycle_diagnostics(&self) -> Option<TileLifecycleDiagnostics>

Return recent tile lifecycle diagnostics for the first visible tile layer, if any.

pub fn background_color(&self) -> Option<[f32; 4]>

Return the effective background Colour from the top-most visible BackgroundLayer, if any.

This gives renderers a backend-owned clear colour similar to MapLibre’s background layer instead of relying only on hard-coded renderer defaults.

pub fn hillshade(&self) -> Option<HillshadeParams>

Return the effective hillshade parameters from the top-most visible HillshadeLayer, if any.

pub fn set_fog(&mut self, config: Option<FogConfig>)

Set the fog/atmosphere configuration override.

When set, the provided FogConfig values override the automatic pitch-based fog computation. None fields in the config fall back to the auto-computed defaults.

Pass None to revert to fully automatic fog.

pub fn fog(&self) -> Option<&FogConfig>

Return the current fog configuration override, if any.

pub fn computed_fog(&self) -> &ComputedFog

Return the pre-computed fog parameters for the current frame.

These are recomputed each frame during update() from camera state, the optional FogConfig, and the background colour. Renderers should read these values directly instead of duplicating the fog math.

pub fn set_lights(&mut self, config: Option<LightConfig>)

Set the lighting configuration override.

When set, the provided LightConfig values override the style document’s "lights" configuration and the engine defaults.

Pass None to revert to the style document’s or default lighting.

pub fn lights(&self) -> Option<&LightConfig>

Return the current lighting configuration override, if any.

pub fn computed_lighting(&self) -> &ComputedLighting

Return the pre-computed lighting parameters for the current frame.

Recomputed each frame during update(). Renderers should read these values directly instead of hardcoding light directions.

pub fn computed_shadow(&self) -> &ComputedShadow

Return the pre-computed shadow cascade parameters for the current frame.

ComputedShadow::enabled is true only when the directional light has cast_shadows = true and lighting is not in flat mode.

pub fn set_sky(&mut self, config: Option<SkyConfig>)

Set the sky / atmosphere configuration override.

When set, the provided SkyConfig enables a procedural sky background. Pass None to disable.

pub fn sky(&self) -> Option<&SkyConfig>

Return the current sky configuration override, if any.

pub fn computed_sky(&self) -> &ComputedSky

Return the pre-computed sky parameters for the current frame.

Recomputed each frame during update().

pub fn style_time(&self) -> f64

Current monotonic style time (seconds), used for transition interpolation.

pub fn layer_transitions(&self) -> &HashMap<StyleLayerId, LayerTransitionState>

Per-layer transition state map.

pub fn resolved_transitions( &self, layer_id: &str, ) -> Option<ResolvedTransitions>

Resolve current transitioned property values for a layer.

Returns None if no transition state has been recorded for the given layer yet.

pub fn set_visible_tiles(&mut self, tiles: Vec<VisibleTile>)

Override the visible tile set for this frame.

pub fn set_terrain_meshes(&mut self, meshes: Vec<TerrainMeshData>)

Override the terrain meshes for this frame (useful for testing).

pub fn set_hillshade_rasters(&mut self, rasters: Vec<PreparedHillshadeRaster>)

Override the prepared hillshade rasters for this frame (useful for testing).

pub fn camera(&self) -> &Camera

Immutable reference to the camera.

pub fn set_viewport(&mut self, width: u32, height: u32)

Set the camera viewport dimensions (logical pixels).

pub fn set_camera_target(&mut self, target: GeoCoord)

Set the camera target geographic coordinate.

Longitude is normalized to [-180, 180) to prevent the camera from drifting into a different world copy, which would cause tile selection to diverge and tiles to stop rendering.

pub fn set_camera_distance(&mut self, distance: f64)

Set the camera distance from the target in meters.

pub fn set_camera_pitch(&mut self, pitch: f64)

Set the camera pitch in radians.

pub fn set_camera_yaw(&mut self, yaw: f64)

Set the camera yaw / bearing in radians.

pub fn set_camera_mode(&mut self, mode: CameraMode)

Set the camera projection mode (perspective / orthographic).

pub fn set_camera_projection(&mut self, projection: CameraProjection)

Set the camera geographic projection used by camera/world helpers.

pub fn set_camera_fov_y(&mut self, fov_y: f64)

Set the vertical field-of-view in radians (perspective mode).

pub fn constraints(&self) -> &CameraConstraints

Immutable reference to the camera constraints.

pub fn set_max_pitch(&mut self, max_pitch: f64)

Set the maximum camera pitch in radians.

pub fn set_min_distance(&mut self, min_distance: f64)

Set the minimum camera distance in meters.

pub fn set_max_distance(&mut self, max_distance: f64)

Set the maximum camera distance in meters.

pub fn layers(&self) -> &LayerStack

Immutable reference to the layer stack.

pub fn push_layer(&mut self, layer: Box<dyn Layer>)

Add a layer to the top of the stack.

pub fn set_grid_scalar( &mut self, name: impl Into<String>, grid: GeoGrid, field: ScalarField2D, ramp: ColorRamp, )

Insert or replace a named grid-scalar visualization layer.

pub fn set_grid_extrusion( &mut self, name: impl Into<String>, grid: GeoGrid, field: ScalarField2D, ramp: ColorRamp, params: ExtrusionParams, )

Insert or replace a named grid-extrusion visualization layer.

pub fn set_instanced_columns( &mut self, name: impl Into<String>, columns: ColumnInstanceSet, ramp: ColorRamp, )

Insert or replace a named instanced-column visualization layer.

pub fn set_point_cloud( &mut self, name: impl Into<String>, points: PointInstanceSet, ramp: ColorRamp, )

Insert or replace a named point-cloud visualization layer.

pub fn style(&self) -> Option<&MapStyle>

Return the currently attached style, if any.

pub fn style_document(&self) -> Option<&StyleDocument>

Return the currently attached style document, if any.

pub fn set_style(&mut self, style: MapStyle) -> Result<(), StyleError>

Replace the current style runtime and re-evaluate terrain + layer state.

pub fn set_style_document( &mut self, document: StyleDocument, ) -> Result<(), StyleError>

Replace the current style document and re-evaluate terrain + layer state.

pub fn with_style_mut<R>( &mut self, mutate: impl FnOnce(&mut StyleDocument) -> R, ) -> Result<Option<R>, StyleError>

Mutate the current style document in place and then re-apply it.

pub fn reapply_style(&mut self) -> Result<bool, StyleError>

Re-evaluate the currently attached style document, if any.

pub fn terrain(&self) -> &TerrainManager

Immutable reference to the terrain manager.

pub fn set_terrain(&mut self, terrain: TerrainManager)

Replace the terrain manager with a new configuration.

pub fn animator(&self) -> &CameraAnimator

Immutable reference to the camera animator.

pub fn is_animating(&self) -> bool

Whether any camera animation is currently active.

pub fn set_data_update_interval(&mut self, interval: f64)

Set the minimum interval (seconds) between full terrain + layer updates while a coordinated camera animation is active.

pub fn data_update_interval(&self) -> f64

Current data-update throttle interval in seconds.

pub fn set_task_pool(&mut self, pool: Arc<dyn DataTaskPool>)

Inject an async task pool for offloading heavy data pipeline work.

pub fn clear_task_pool(&mut self)

Remove the async task pool, reverting to synchronous execution.

pub fn has_async_pipeline(&self) -> bool

Whether an async task pool is currently active.

pub fn vector_meshes(&self) -> &[VectorMeshData]

Tessellated vector meshes from the last update.

pub fn model_instances(&self) -> &[ModelInstance]

3D model instances from the last update.

pub fn placed_symbols(&self) -> &[PlacedSymbol]

Placed symbols from the last update.

pub fn symbol_assets(&self) -> &SymbolAssetRegistry

Symbol asset dependency state for the last update.

pub fn feature_state( &self, source_id: &str, feature_id: &str, ) -> Option<&FeatureState>

Look up feature state for a source-local feature id.

pub fn set_feature_state( &mut self, source_id: impl Into<String>, feature_id: impl Into<String>, state: FeatureState, )

Replace feature state for a source-local feature id.

pub fn set_feature_state_property( &mut self, source_id: impl Into<String>, feature_id: impl Into<String>, key: impl Into<String>, value: PropertyValue, )

Set a single feature-state property.

pub fn remove_feature_state( &mut self, source_id: &str, feature_id: &str, ) -> Option<FeatureState>

Remove feature state for a source-local feature id.

pub fn clear_feature_state(&mut self)

Clear all stored feature state.

pub fn resolve_feature_style( &self, style_layer_id: &str, source_id: &str, feature_id: &str, ) -> Option<VectorStyle>

Resolve a style layer’s paint properties for a specific feature’s current state.

This is the primary convenience method for hover/selection restyling: it looks up the named style layer, retrieves the feature’s current state from the internal store, and evaluates all paint properties through the [StyleEvalContextFull] path.

Returns None when:

• no style document is attached
• the layer id does not exist in the style document
• the layer type does not produce a VectorStyle (background, hillshade, raster, model)

Example

map.set_feature_state_property("source", "feat-42", "hover", PropertyValue::Bool(true));
if let Some(style) = map.resolve_feature_style("buildings", "source", "feat-42") {
    // `style` has paint values resolved with hover=true.
}

pub fn set_interaction_manager(&mut self, manager: InteractionManager)

Attach an interaction manager for automatic hover/leave/click lifecycle.

Once set, the host feeds raw pointer events into the manager (via interaction_manager_mut) and drains high-level InteractionEvents each frame.

pub fn take_interaction_manager(&mut self) -> Option<InteractionManager>

Remove the attached interaction manager, returning it if present.

pub fn interaction_manager(&self) -> Option<&InteractionManager>

Read-only access to the attached interaction manager.

pub fn interaction_manager_mut(&mut self) -> Option<&mut InteractionManager>

Mutable access to the attached interaction manager.

Use this to feed pointer events and drain emitted interaction events.

pub fn on<F>(&mut self, kind: InteractionEventKind, callback: F) -> ListenerId

where F: Fn(&InteractionEvent) + Send + Sync + 'static,

Subscribe to interaction events of a given kind.

Returns a ListenerId for later removal via off.

pub fn once<F>(&mut self, kind: InteractionEventKind, callback: F) -> ListenerId

where F: Fn(&InteractionEvent) + Send + Sync + 'static,

Subscribe to a single occurrence of an interaction event kind.

The listener is automatically removed after the first dispatch.

pub fn off(&mut self, id: ListenerId) -> bool

Unsubscribe a previously registered event listener.

pub fn dispatch_events(&mut self, events: &[InteractionEvent])

Dispatch interaction events to registered listeners.

Call this after draining events from the interaction manager. Events are forwarded to all matching on / once callbacks.

pub fn event_emitter_mut(&mut self) -> &mut EventEmitter

Mutable access to the event emitter for advanced use cases.

pub fn invalidate_symbol_image_dependency(&mut self, image_id: &str) -> usize

Invalidate placed-symbol tiles that depend on the given image id.

pub fn invalidate_symbol_glyph_dependency( &mut self, font_stack: &str, codepoint: char, ) -> usize

Invalidate placed-symbol tiles that depend on the given glyph.

pub fn set_vector_meshes(&mut self, meshes: Vec<VectorMeshData>)

Override the vector meshes for this frame (useful for testing).

pub fn set_model_instances(&mut self, instances: Vec<ModelInstance>)

Override the model instances for this frame (useful for testing).

pub fn set_placed_symbols(&mut self, symbols: Vec<PlacedSymbol>)

Override the placed symbols for this frame (useful for testing).

pub fn update_with_dt(&mut self, dt: f64)

Recompute all derived state with an explicit delta-time (seconds).

pub fn handle_input(&mut self, event: InputEvent)

Forward an input event to the camera controller.

Touch events are routed through the built-in GestureRecognizer, which converts multi-touch sequences into pan / zoom / rotate events before forwarding them to the camera controller.

pub fn gesture_recognizer(&self) -> &GestureRecognizer

Access the gesture recognizer (e.g. to call reset).

pub fn update(&mut self)

Convenience: calls update_with_dt(1.0 / 60.0).

pub fn fly_to(&mut self, options: FlyToOptions)

Begin a fly-to animation.

pub fn ease_to(&mut self, options: EaseToOptions)

Begin an ease-to animation.

pub fn jump_to( &mut self, target: GeoCoord, distance: f64, pitch: Option<f64>, yaw: Option<f64>, )

Immediately jump the camera to the given state.

pub fn update_camera(&mut self, dt: f64)

Tick the camera animator and recompute zoom / viewport / frustum.

pub fn frame_output(&self) -> FrameOutput

Build a detached per-frame snapshot for renderers.

pub fn elevation_at(&self, coord: &GeoCoord) -> Option<f64>

Query the terrain elevation at a geographic coordinate.

pub fn screen_to_geo(&self, px: f64, py: f64) -> Option<GeoCoord>

Unproject a screen pixel to a geographic coordinate (flat ground).

pub fn geo_to_screen(&self, geo: &GeoCoord) -> Option<(f64, f64)>

Project a geographic coordinate to a screen-space pixel position.

Returns (px, py) in logical pixels with (0, 0) at the top-left corner of the viewport, or None if the point is behind the camera.

pub fn fit_bounds(&mut self, bounds: &GeoBounds, options: &FitBoundsOptions)

Fit the camera to a geographic bounding box.

Computes the center and zoom level that make the entire bounding box visible, accounting for optional padding. Depending on options.animate, the transition may be animated (fly_to) or instant (jump_to).

pub fn ray_to_geo(&self, origin: DVec3, direction: DVec3) -> Option<GeoCoord>

Cast a ray and intersect with the flat ground plane (z = 0).

pub fn ray_to_geo_on_terrain( &self, origin: DVec3, direction: DVec3, ) -> Option<GeoCoord>

Cast a ray and intersect with the terrain surface.

Falls back to flat ground intersection if terrain is disabled or no intersection is found.

pub fn ray_to_flat_geo( &self, origin: DVec3, direction: DVec3, ) -> Option<GeoCoord>

Cast a ray and intersect with the flat ground plane, ignoring terrain.

pub fn screen_to_geo_on_terrain(&self, px: f64, py: f64) -> Option<GeoCoord>

Screen-to-geo through the terrain surface.

Trait Implementations

impl Default for MapState

fn default() -> Self

Returns the “default value” for a type.