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.

pub fn set_style_json(&self, json: &str) -> Result<()>

Loads inline style JSON through MapLibre Native style APIs.

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. It is released on source removal, map close/drop, successful inline JSON style replacement, or after runtime event polling observes that the loaded style no longer contains the source. Native may invoke callbacks from worker threads; callbacks should queue owner-thread work before calling map APIs.

pub fn set_custom_geometry_source_tile_data( &self, source_id: &str, tile_id: CanonicalTileId, data: &GeoJson, ) -> 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: &JsonValue, ) -> 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 fixed metadata and attribution for one style source.

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

Adds a GeoJSON source with inline data.

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

Updates one GeoJSON source with inline data.

pub fn add_style_layer_json( &self, layer_json: &JsonValue, 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<JsonValue>>

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

pub fn set_style_light_json(&self, light_json: &JsonValue) -> Result<()>

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

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

Sets one style light property.

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

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

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

Sets one layer style property.

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

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

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

Sets or clears one layer filter.

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

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

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 new(runtime: &RuntimeHandle) -> Result<Self>

Creates a map with native default map options on the runtime owner thread.

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.

Native destruction errors are returned. When destruction fails, the underlying native handle remains live in the shared state so future child handles can continue to retain and close the map safely.

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

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

Applies a camera fly transition command.

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.

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.

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.

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.

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

Cancels active camera transitions.

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: &Geometry, 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 wrapped geographic bounds for a camera in the current viewport.

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

Computes unwrapped geographic bounds for a camera in the current viewport.

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_metal_surface( &self, descriptor: &MetalSurfaceDescriptor, ) -> Result<RenderSessionHandle>

Attaches a Metal native surface render target to this map.

The layer and optional device pointers are backend-native handles. They must name valid Metal objects for this session and remain usable on the owner thread until the session is detached or closed.

pub fn attach_vulkan_surface( &self, descriptor: &VulkanSurfaceDescriptor, ) -> Result<RenderSessionHandle>

Attaches a Vulkan native surface render target to this map.

Vulkan handles are borrowed. They must remain valid and externally synchronized until the session is detached or closed.

pub fn attach_opengl_surface( &self, descriptor: &OpenGLSurfaceDescriptor, ) -> Result<RenderSessionHandle>

Attaches an OpenGL native surface render target to this map.

OpenGL context provider and surface handles are borrowed. They must remain valid and externally synchronized until the session is detached or closed.

pub fn attach_metal_owned_texture( &self, descriptor: &MetalOwnedTextureDescriptor, ) -> Result<RenderSessionHandle>

Attaches a Metal session-owned texture render target to this map.

The device pointer must name a valid Metal device that remains usable on the owner thread until the session is detached or closed.

pub fn attach_metal_borrowed_texture( &self, descriptor: &MetalBorrowedTextureDescriptor, ) -> Result<RenderSessionHandle>

Attaches a Metal caller-owned texture render target to this map.

The texture pointer is borrowed. The caller owns the texture, keeps it valid until detach or close, and synchronizes use outside this session.

pub fn attach_vulkan_owned_texture( &self, descriptor: &VulkanOwnedTextureDescriptor, ) -> Result<RenderSessionHandle>

Attaches a Vulkan session-owned texture render target to this map.

Vulkan device and queue handles are borrowed. They must remain valid and externally synchronized until the session is detached or closed.

pub fn attach_vulkan_borrowed_texture( &self, descriptor: &VulkanBorrowedTextureDescriptor, ) -> Result<RenderSessionHandle>

Attaches a Vulkan caller-owned texture render target to this map.

Vulkan handles, image, and image view are borrowed. The caller owns the image resources, keeps them valid until detach or close, and handles queue-family ownership and synchronization outside this session.

pub fn attach_opengl_owned_texture( &self, descriptor: &OpenGLOwnedTextureDescriptor, ) -> Result<RenderSessionHandle>

Attaches an OpenGL session-owned texture render target to this map.

The context provider handles are borrowed. They must remain valid until the session is detached or closed. Host sampling must use a context in the same share group while the acquired frame remains open.

pub fn attach_opengl_borrowed_texture( &self, descriptor: &OpenGLBorrowedTextureDescriptor, ) -> Result<RenderSessionHandle>

Attaches an OpenGL caller-owned texture render target to this map.

The context provider handles and texture object are borrowed. The caller owns the texture, keeps it valid until detach or close, and synchronizes use outside this session.

Trait Implementations

impl Debug for MapHandle

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

Formats the value using the given formatter.