Struct MapHandle 

pub struct MapHandle { /* private fields */ }

Owner-thread map handle bound to a retained runtime.

Implementations

impl MapHandle

pub fn set_style_url(&self, url: &str) -> Result<()>

Loads a style URL through MapLibre Native style APIs.

Loading is asynchronous: a style that fails to fetch or parse still returns Ok here and reports through a later loading-failed runtime event. Watch the event stream for the load outcome.

pub fn set_style_json(&self, json: &[u8]) -> Result<()>

Loads inline style JSON through MapLibre Native style APIs.

A parse failure is reported twice: this call returns the error, and the same message arrives as a loading-failed runtime event.

pub fn loaded_style_json(&self) -> Result<Vec<u8>>

Copies the style document this map’s style was last parsed from: the string given to Self::set_style_json or the body fetched for Self::set_style_url, byte for byte. Runtime mutations do not change it. An empty buffer means no document has been parsed.

pub fn style_url(&self) -> Result<String>

Copies the URL this map’s style was last requested from.

Self::set_style_url records the URL when the request is made, before the response arrives, and Self::set_style_json clears it, so this can disagree with Self::loaded_style_json while a load is in flight. An empty string means no URL bytes are available.

pub fn add_custom_geometry_source( &self, source_id: &str, options: CustomGeometrySourceOptions, ) -> Result<()>

Adds a custom geometry source to the current style.

The callback state is scoped to this map’s current style. The C API frees it once it stops referencing it, whether the source is removed, dropped by a style load, or retired with the map. Native may invoke callbacks from worker threads, so queue owner-thread work before calling map APIs.

pub fn set_custom_geometry_source_tile_data( &self, source_id: &str, tile_id: CanonicalTileId, data: &[u8], ) -> Result<()>

Sets custom geometry source data for one canonical tile.

pub fn invalidate_custom_geometry_source_tile( &self, source_id: &str, tile_id: CanonicalTileId, ) -> Result<()>

Invalidates custom geometry source data for one canonical tile.

pub fn invalidate_custom_geometry_source_region( &self, source_id: &str, bounds: LatLngBounds, ) -> Result<()>

Invalidates custom geometry source data inside a geographic region.

pub fn add_style_source_json( &self, source_id: &str, source_json: &[u8], ) -> Result<()>

Adds one style source from a style-spec source JSON object.

pub fn add_vector_source_url( &self, source_id: &str, url: &str, options: Option<&TileSourceOptions>, ) -> Result<()>

Adds a vector source with a TileJSON URL.

pub fn add_vector_source_tiles<S: AsRef<str>>( &self, source_id: &str, tiles: &[S], options: Option<&TileSourceOptions>, ) -> Result<()>

Adds a vector source with inline tile URLs.

pub fn add_raster_source_url( &self, source_id: &str, url: &str, options: Option<&TileSourceOptions>, ) -> Result<()>

Adds a raster source with a TileJSON URL.

pub fn add_raster_source_tiles<S: AsRef<str>>( &self, source_id: &str, tiles: &[S], options: Option<&TileSourceOptions>, ) -> Result<()>

Adds a raster source with inline tile URLs.

pub fn add_raster_dem_source_url( &self, source_id: &str, url: &str, options: Option<&TileSourceOptions>, ) -> Result<()>

Adds a raster DEM source with a TileJSON URL.

pub fn add_raster_dem_source_tiles<S: AsRef<str>>( &self, source_id: &str, tiles: &[S], options: Option<&TileSourceOptions>, ) -> Result<()>

Adds a raster DEM source with inline tile URLs.

pub fn add_image_source_url( &self, source_id: &str, coordinates: &[LatLng; 4], url: &str, ) -> Result<()>

Adds an image source that loads its image from a URL.

Coordinates are borrowed for the call and copied by native on success. The array entries are in top-left, top-right, bottom-right, bottom-left order.

pub fn add_image_source_image( &self, source_id: &str, coordinates: &[LatLng; 4], image: &PremultipliedRgba8Image, ) -> Result<()>

Adds an image source with inline premultiplied RGBA8 pixels.

Coordinates and image pixels are borrowed for the call and copied by native on success. Coordinate entries are in top-left, top-right, bottom-right, bottom-left order.

pub fn set_image_source_url(&self, source_id: &str, url: &str) -> Result<()>

Updates an image source to load its image from a URL.

pub fn set_image_source_image( &self, source_id: &str, image: &PremultipliedRgba8Image, ) -> Result<()>

Updates an image source with inline premultiplied RGBA8 pixels.

pub fn set_image_source_coordinates( &self, source_id: &str, coordinates: &[LatLng; 4], ) -> Result<()>

Updates image source coordinates.

Coordinates are borrowed for the call and copied by native on success. The array entries are in top-left, top-right, bottom-right, bottom-left order.

pub fn image_source_coordinates( &self, source_id: &str, ) -> Result<Option<[LatLng; 4]>>

Copies image source coordinates into owned Rust values.

pub fn remove_style_source(&self, source_id: &str) -> Result<bool>

Removes one style source by ID.

Returns whether a source existed and was removed. Native returns an error when a layer still uses the source.

pub fn style_source_exists(&self, source_id: &str) -> Result<bool>

Reports whether a style source ID exists.

pub fn set_style_image( &self, image_id: &str, image: &PremultipliedRgba8Image, options: Option<&StyleImageOptions>, ) -> Result<()>

Adds or replaces one runtime style image.

pub fn remove_style_image(&self, image_id: &str) -> Result<bool>

Removes one runtime style image by ID.

Returns whether an image existed and was removed.

pub fn style_image_exists(&self, image_id: &str) -> Result<bool>

Reports whether a runtime style image ID exists.

pub fn style_image_info(&self, image_id: &str) -> Result<Option<StyleImageInfo>>

Copies fixed metadata for one runtime style image.

pub fn copy_style_image_premultiplied_rgba8( &self, image_id: &str, ) -> Result<Option<StyleImage>>

Copies one runtime style image into owned tightly packed premultiplied RGBA8 pixels.

pub fn style_source_type(&self, source_id: &str) -> Result<Option<SourceType>>

Gets one style source type.

pub fn style_source_info(&self, source_id: &str) -> Result<Option<SourceInfo>>

Copies retained metadata for one style source.

pub fn add_geojson_source_url( &self, source_id: &str, url: &str, options: Option<&GeoJsonSourceOptions>, ) -> Result<()>

Adds a GeoJSON source that loads data from a URL. options are fixed at creation; later data or URL updates keep them.

pub fn add_geojson_source_data( &self, source_id: &str, data: &GeoJsonSourceDataHandle, ) -> Result<()>

Adds a GeoJSON source with prepared inline data.

The call borrows data, and the source adopts the options the data was prepared with, fixed for the lifetime of the source.

pub fn set_geojson_source_url(&self, source_id: &str, url: &str) -> Result<()>

Updates one GeoJSON source to load data from a URL.

The source keeps the options it was added with.

pub fn set_geojson_source_data( &self, source_id: &str, data: &GeoJsonSourceDataHandle, ) -> Result<()>

Updates one GeoJSON source with prepared inline data.

The call borrows data, and the expensive parse and tiling already happened when the data was prepared, so the install is cheap. The data must have been prepared with options equal to the options the source was added with, cluster_properties excepted; a mismatch is rejected.

pub fn set_geojson_source_synchronous_tiling( &self, source_id: &str, enabled: bool, ) -> Result<()>

Overrides one GeoJSON source’s synchronous tiling at runtime.

While enabled, the source slices requested tiles inline during the update pass, as if its options had set synchronous_tiling; disabling restores the option the source was added with. The override applies to update passes after this call returns.

pub fn add_style_layer_json( &self, layer_json: &[u8], before_layer_id: Option<&str>, ) -> Result<()>

Adds one style layer from a full style-spec layer JSON object.

pub fn add_hillshade_layer( &self, layer_id: &str, source_id: &str, before_layer_id: Option<&str>, ) -> Result<()>

Adds a hillshade layer for a raster DEM source.

pub fn add_color_relief_layer( &self, layer_id: &str, source_id: &str, before_layer_id: Option<&str>, ) -> Result<()>

Adds a color-relief layer for a raster DEM source.

pub fn add_location_indicator_layer( &self, layer_id: &str, before_layer_id: Option<&str>, ) -> Result<()>

Adds a source-free location indicator layer.

pub fn set_location_indicator_location( &self, layer_id: &str, coordinate: LatLng, altitude: f64, ) -> Result<()>

Sets a location indicator layer location.

pub fn set_location_indicator_bearing( &self, layer_id: &str, bearing: f64, ) -> Result<()>

Sets a location indicator layer bearing in degrees.

pub fn set_location_indicator_accuracy_radius( &self, layer_id: &str, radius: f64, ) -> Result<()>

Sets a location indicator layer accuracy radius in logical pixels.

pub fn set_location_indicator_image_name( &self, layer_id: &str, image_kind: LocationIndicatorImageKind, image_id: &str, ) -> Result<()>

Sets one location indicator image-name property.

pub fn style_layer_json(&self, layer_id: &str) -> Result<Option<Vec<u8>>>

Copies one style layer as a full style-spec JSON object.

pub fn set_style_light_json(&self, light_json: &[u8]) -> Result<()>

Sets the style light from a style-spec light JSON object.

pub fn set_style_light_property( &self, property_name: &str, value: &[u8], ) -> Result<()>

Sets one style light property.

pub fn style_light_property( &self, property_name: &str, ) -> Result<Option<Vec<u8>>>

Copies one style light property as a style-spec JSON value.

pub fn set_style_transition_options( &self, options: &StyleTransitionOptions, ) -> Result<()>

Sets the style’s global transition options. This replaces the whole configuration rather than merging, and loading a style replaces it again, so apply an override after the style loads.

pub fn style_transition_options(&self) -> Result<StyleTransitionOptions>

Reads the style’s global transition options.

pub fn set_layer_property( &self, layer_id: &str, property_name: &str, value: &[u8], ) -> Result<()>

Sets one layer style property.

pub fn layer_property( &self, layer_id: &str, property_name: &str, ) -> Result<Option<Vec<u8>>>

Copies one layer style property as a style-spec JSON value.

pub fn set_layer_filter( &self, layer_id: &str, filter: Option<&[u8]>, ) -> Result<()>

Sets or clears one layer filter.

pub fn layer_filter(&self, layer_id: &str) -> Result<Option<Vec<u8>>>

Copies one layer filter as a style-spec JSON value.

pub fn style_image_stretches( &self, image_id: &str, ) -> Result<Option<(Vec<ImageStretch>, Vec<ImageStretch>)>>

Copies one runtime style image’s stretchable intervals.

Returns None when no image carries image_id.

pub fn set_layer_source_layer( &self, layer_id: &str, source_layer: &str, ) -> Result<()>

Sets one layer’s source-layer ID.

Layer types that take no source, such as background, are rejected.

pub fn layer_source_layer(&self, layer_id: &str) -> Result<String>

Copies one layer’s source-layer ID, empty when the layer carries none.

pub fn set_layer_source_id(&self, layer_id: &str, source_id: &str) -> Result<()>

Sets one layer’s source ID.

Layer types that take no source, such as background, are rejected. The named source need not exist yet.

pub fn layer_source_id(&self, layer_id: &str) -> Result<String>

Copies one layer’s source ID, empty when the layer carries none.

pub fn set_layer_min_zoom(&self, layer_id: &str, min_zoom: f64) -> Result<()>

Sets the lowest zoom at which one layer draws.

Pass f64::NEG_INFINITY for no lower bound.

pub fn layer_min_zoom(&self, layer_id: &str) -> Result<f64>

Reads the lowest zoom at which one layer draws.

A layer with no lower bound reports f64::NEG_INFINITY.

pub fn set_layer_max_zoom(&self, layer_id: &str, max_zoom: f64) -> Result<()>

Sets the highest zoom at which one layer draws.

Pass f64::INFINITY for no upper bound.

pub fn layer_max_zoom(&self, layer_id: &str) -> Result<f64>

Reads the highest zoom at which one layer draws.

A layer with no upper bound reports f64::INFINITY.

pub fn set_layer_visibility( &self, layer_id: &str, visibility: StyleLayerVisibility, ) -> Result<()>

Sets whether one layer draws.

pub fn layer_visibility(&self, layer_id: &str) -> Result<StyleLayerVisibility>

Reads whether one layer draws.

pub fn style_source_ids(&self) -> Result<Vec<String>>

Copies current style source IDs into owned Rust strings.

pub fn style_layer_ids(&self) -> Result<Vec<String>>

Copies current style layer IDs into owned Rust strings.

impl MapHandle

pub fn with_options( runtime: &RuntimeHandle, options: &MapOptions, ) -> Result<Self>

Creates a map with explicit map options on the runtime owner thread.

pub fn id(&self) -> MapId

Returns this map’s runtime-local event source identity.

pub fn close(self) -> Result<(), HandleOperationError<Self>>

Explicitly destroys the map. A failed destroy leaves the native handle live so child handles can keep retaining and closing the map.

Closing discards this map’s queued runtime events and its recorded loading failure, with no flush and no terminal event. Dropping the handle ends the event stream the same way.

pub fn request_repaint(&self) -> Result<()>

Requests a repaint for a continuous map.

pub fn request_still_image(&self) -> Result<()>

Requests one still image for a static or tile map.

pub fn set_event_mask(&self, mask: RuntimeEventMask) -> Result<()>

Selects which map-originated event types this map queues.

A map reads the bits in RuntimeEventMask::ALL_MAP_EVENTS, so RuntimeEventMask::ALL selects every map-originated type. Narrowing gates later events and keeps queued ones. A bit outside ALL is an invalid-argument error.

pub fn event_mask(&self) -> Result<RuntimeEventMask>

Reports which map-originated event types this map queues, starting from the mask its creation options selected.

pub fn set_debug_options(&self, options: MapDebugOptions) -> Result<()>

Applies MapLibre debug overlay mask bits.

pub fn debug_options(&self) -> Result<MapDebugOptions>

Reads MapLibre debug overlay mask bits.

pub fn set_rendering_stats_view_enabled(&self, enabled: bool) -> Result<()>

Enables or disables MapLibre’s rendering stats overlay view.

pub fn rendering_stats_view_enabled(&self) -> Result<bool>

Reads whether MapLibre’s rendering stats overlay view is enabled.

pub fn is_fully_loaded(&self) -> Result<bool>

Reads whether MapLibre currently considers the map fully loaded.

pub fn dump_debug_logs(&self) -> Result<()>

Dumps map debug logs through MapLibre Native logging.

pub fn size(&self) -> Result<(u32, u32, f64)>

Reads the map’s logical viewport size in UI pixels and its pixel ratio. The scale factor is fixed for the lifetime of the map and independent of any render target’s scale factor.

pub fn viewport_options(&self) -> Result<MapViewportOptions>

Reads live viewport and render-transform controls.

pub fn set_viewport_options(&self, options: &MapViewportOptions) -> Result<()>

Applies selected live viewport and render-transform controls.

pub fn tile_options(&self) -> Result<MapTileOptions>

Reads tile prefetch and LOD tuning controls.

pub fn set_tile_options(&self, options: &MapTileOptions) -> Result<()>

Applies selected tile prefetch and LOD tuning controls.

pub fn camera(&self) -> Result<CameraOptions>

Reads the current camera snapshot.

pub fn jump_to(&self, camera: &CameraOptions) -> Result<()>

Applies a camera jump command.

pub fn ease_to( &self, camera: &CameraOptions, animation: Option<&AnimationOptions>, ) -> Result<()>

Applies a camera ease transition command. An absent animation, or one with no duration, reaches the target before this call returns.

pub fn fly_to( &self, camera: &CameraOptions, animation: Option<&AnimationOptions>, ) -> Result<()>

Applies a camera fly transition command. Fly animates by default, so the camera is still en route when this call returns and advances as the runtime is pumped.

pub fn move_by(&self, delta_x: f64, delta_y: f64) -> Result<()>

Applies a screen-space pan command.

pub fn move_by_animated( &self, delta_x: f64, delta_y: f64, animation: Option<&AnimationOptions>, ) -> Result<()>

Applies an animated screen-space pan command. An absent animation, or one with no duration, applies the pan instantly.

pub fn scale_by(&self, scale: f64, anchor: Option<ScreenPoint>) -> Result<()>

Applies a screen-space zoom command.

pub fn scale_by_animated( &self, scale: f64, anchor: Option<ScreenPoint>, animation: Option<&AnimationOptions>, ) -> Result<()>

Applies an animated screen-space zoom command. An absent animation, or one with no duration, applies the zoom instantly.

pub fn rotate_by(&self, first: ScreenPoint, second: ScreenPoint) -> Result<()>

Applies a screen-space rotate command.

pub fn rotate_by_animated( &self, first: ScreenPoint, second: ScreenPoint, animation: Option<&AnimationOptions>, ) -> Result<()>

Applies an animated screen-space rotate command. An absent animation, or one with no duration, applies the rotation instantly.

pub fn pitch_by(&self, pitch: f64) -> Result<()>

Applies a pitch delta command.

pub fn pitch_by_animated( &self, pitch: f64, animation: Option<&AnimationOptions>, ) -> Result<()>

Applies an animated pitch delta command. An absent animation, or one with no duration, applies the pitch instantly.

pub fn cancel_transitions(&self) -> Result<()>

Cancels active camera transitions.

pub fn set_gesture_in_progress(&self, in_progress: bool) -> Result<()>

Marks whether a host-driven gesture is in progress. The flag stays set until the host clears it, so pair every true with a false.

pub fn is_gesture_in_progress(&self) -> Result<bool>

Reads whether a host-driven gesture is currently in progress.

pub fn camera_for_lat_lng_bounds( &self, bounds: LatLngBounds, fit_options: Option<&CameraFitOptions>, ) -> Result<CameraOptions>

Computes a camera that fits geographic bounds in the current viewport.

pub fn camera_for_lat_lngs( &self, coordinates: &[LatLng], fit_options: Option<&CameraFitOptions>, ) -> Result<CameraOptions>

Computes a camera that fits geographic coordinates in the current viewport.

pub fn camera_for_geometry( &self, geometry: &[u8], fit_options: Option<&CameraFitOptions>, ) -> Result<CameraOptions>

Computes a camera that fits a geometry in the current viewport.

pub fn lat_lng_bounds_for_camera( &self, camera: &CameraOptions, ) -> Result<LatLngBounds>

Computes geographic bounds for a camera from two viewport corners.

The box is the hull of the top-left and bottom-right screen corners for that camera in the current viewport. When bearing and pitch are zero, the box equals the visible area. Those corners are the northwest and southeast of the viewport. Longitudes stay in -180 to 180.

pub fn lat_lng_bounds_for_camera_unwrapped( &self, camera: &CameraOptions, ) -> Result<LatLngBounds>

Computes geographic bounds for a camera from the four viewport corners.

The axis-aligned hull of all four screen corners and the center encompasses the projected viewport. Longitudes unwrap onto the shortest path through the center. A viewport that crosses the antimeridian reports values outside -180 to 180.

pub fn bounds(&self) -> Result<BoundOptions>

Reads map camera constraint options.

pub fn set_bounds(&self, options: &BoundOptions) -> Result<()>

Applies selected map camera constraint options.

pub fn free_camera_options(&self) -> Result<FreeCameraOptions>

Reads the current free camera position and orientation.

pub fn set_free_camera_options(&self, options: &FreeCameraOptions) -> Result<()>

Applies selected free camera position and orientation fields.

pub fn projection_mode(&self) -> Result<ProjectionMode>

Reads current axonometric rendering options.

pub fn set_projection_mode(&self, mode: &ProjectionMode) -> Result<()>

Applies selected axonometric rendering option fields.

pub fn pixel_for_lat_lng(&self, coordinate: LatLng) -> Result<ScreenPoint>

Converts a geographic world coordinate to a screen point for the current map.

pub fn lat_lng_for_pixel(&self, point: ScreenPoint) -> Result<LatLng>

Converts a screen point to a geographic world coordinate for the current map.

pub fn pixels_for_lat_lngs( &self, coordinates: &[LatLng], ) -> Result<Vec<ScreenPoint>>

Converts geographic world coordinates to screen points for the current map.

pub fn lat_lngs_for_pixels(&self, points: &[ScreenPoint]) -> Result<Vec<LatLng>>

Converts screen points to geographic world coordinates for the current map.

pub fn create_projection(&self) -> Result<MapProjectionHandle>

Creates a standalone projection snapshot from the current map transform.

pub fn attach_ref(&self) -> Result<MapAttachRef>

Produces a Send reference to this map for attaching a render session. A render session is owned by the thread that attaches it, which need not be the map’s owner thread.

Trait Implementations

impl Debug for MapHandle

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.