Crate maplibre_native

Expand description

§MapLibre-native-rs

Rust bindings to the MapLibre Native map rendering engine.

§Usage

We use maplibre-natives’ “core library”, a static, pre-compiled library. We also allow you to compile this yourself. Instructions for this are below.

§Backend Features

This crate supports multiple rendering backends:

vulkan (default on Linux/Windows): cargo build --features vulkan
metal (default on macOS/iOS): cargo build --features metal
opengl (Linux/Windows): cargo build --features opengl

On Linux, OpenGL uses EGL by default for headless rendering. Use the glx feature only when you explicitly need rendering through GLX/X11.

We also support the following other features (all enabled by default):

json: load styles and layers from JSON via serde_json
geojson: interoperate with the geojson crate
log: logging via the log crate

At its core, we work as follows:

use maplibre_native::{CameraUpdate, ImageRendererBuilder, Image, LatLng};
use std::num::NonZeroU32;

let mut renderer = ImageRendererBuilder::new()
                      .with_size(NonZeroU32::new(512).unwrap(),NonZeroU32::new(512).unwrap())
                      .build_static_renderer();
renderer.load_style_from_url(&"https://demotiles.maplibre.org/style.json".parse().unwrap());
let camera = CameraUpdate::new()
    .center(LatLng { lat: 0.0, lng: 0.0 })
    .zoom(0.0);
let image: Image = renderer.render_static(&camera).unwrap();

// Access the underlying ImageBuffer for all operations
let img_buffer = image.as_image();
println!("Image dimensions: {}x{}", img_buffer.width(), img_buffer.height());
img_buffer.save("map.png").unwrap();

TIP: Next to the static rendering map mode, we also have continous and a tile based one. Continous is desiged to be interactive, while the tile based one is primarily for tile servers

§Platform Support

The following platform and rendering-API combinations are supported and tested in CI:

Platform	Metal	Vulkan	OpenGL
Linux x86	❌	✅	✅
Linux ARM	❌	✅	✅
Windows x86	❌	🟨	🟨
Windows ARM	❌	🟨	🟨
macOS ARM	✅	✅¹	❌

_{✅ = IS supported and tested in CI
🟨 = SHOULD be supported, but currently is not
❌ = Not possible}

§Dependencies

This command will install the required dependencies on Linux or macOS for the vulkan backend. You may also use it with the opengl or glx parameter on Linux. It is OK to run this command multiple times for each backend.

just install-dependencies vulkan

§Getting the core library

Since we wrap the Maplibre native library, we need this and its headers to be included.

By default the library will be downloaded and build locally during the build process of maplibre-native-rs.

We can get the library and headers from two places:

default: library will be downloaded and build locally during the build process of maplibre-native-rs
The specific version is controllable from the `build.rs` file.
downloaded from the releases page

The specific version of MapLibre Native used is controlled by package.metadata.mln.release in Cargo.toml. This dependency is automatically updated via a GitHub workflow on the 1st of each month repository. A pull request is created if an update is available.
if the env vars MLN_PRECOMPILEMLN_CORE_LIBRARY_PATH and MLN_CORE_HEADERS_PATH are set: from local disk via the environment variables

If you don’t want to allow network access during buildscript execution, we allow you to download the release and tell us where you have downloaded the contents. You can also build from source by following the steps that maplibre-native does in CI to produce the artefacts.

§Development

This project is easier to develop with just, a modern alternative to make. Install it with cargo install just.
To get a list of available commands, run just.
To run tests, use just test.

§Getting Involved

Join the #maplibre-martin slack channel at OSMUS – automatic invite is at https://slack.openstreetmap.us/

§License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT) at your option.

§Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual-licensed as above, without any additional terms or conditions.

§`MapLibre Native` Licence

This crate incorporates MapLibre Native assets during compilation by downloading and statically linking them. As a result, any project using this crate must comply with the MapLibre Native License (BSD 2-Clause) requirements for binary distribution. This includes providing proper attribution and including the license text with your distributed binaries or source code.

Vulkan support on macos is provided via MoltenVK. There is a slight performance overhead for this with little upsides. Both Metal and Vulkan run through the same extensive test suite upstream. You can use Vulkan if you find a bug in the Metal implementation until we have fixed it upstream. ↩

Modules§

callbacks: Callback types used by the renderer event API.
file_source: Rust-supplied FileSource callback.
tile_server_options: Tile server options builder.

Structs§

CameraUpdate: A partial camera update.
CircleLayer: A circle layer for rendering point data.
Color: A color constructed from straight RGBA channels in the 0.0..=1.0 range.
Continuous: Internal state type to render continuously
EdgeInsets: Insets from each edge of the renderer viewport.
FileSourceRequestCallback: Callback object
FillLayer: A fill layer for rendering polygon data.
FsErrorReason: Error reason categories — mirror of mbgl::Response::Error::Reason.
GeoJson: A GeoJSON value prepared for MapLibre Native.
GeoJsonSource: A GeoJSON source for rendering geographic data.
GeoJsonSourceRefMut: A mutable reference to a GeoJSON source owned by the current style.
Image: A rendered map image.
ImageId: A stable image ID handle that can be used after an image object is moved.
ImageRenderer: Configuration options for a tile server.
ImageRendererBuilder: Builder for configuring ImageRenderer instances
LatLng: A geographic coordinate.
LatLngBounds: A geographic bounding box.
LayerId: Stable layer ID handle that can be used after a layer object is moved.
LineLayer: A line layer for rendering line data.
MapDebugOptions: Debug visualization options for map rendering.
MapLoadError: Error reported while loading a map or style.
MapMode: Map rendering mode configuration.
MapObserver: Object to modify the map observer callbacks
MapObserverCameraChangeMode: Camera change mode for map observer callbacks.
OpaqueLayer: A style layer of a type that does not (yet) have a typed Rust wrapper.
OpaqueSource: A style source of a type that does not (yet) have a typed Rust wrapper.
OpaqueSourceRefMut: A mutable reference to a style-owned source without a typed Rust wrapper.
RenderRequest: In-flight render request.
ResourceKind: Resource kinds — mirror of mbgl::Resource::Kind.
ResourceOptions: Resource Options
RunLoopHandle: Handle to the current thread’s MapLibre Native run loop.
ScreenCoordinate: A position in screen coordinates
Size: A size
SourceId: Stable source ID handle that can be used after a source object is moved.
Static: Internal state type to render a static map image.
StyleLoadError: Error returned when a style fails to load.
StyleLoadRequest: In-flight style load request.
StyleRef: A mutable reference to the renderer’s current map style.
SymbolLayer: A symbol layer for rendering labels and icons on the map.
Tile: Internal state type to render a map tile.

Enums§

AnyLayer: A style layer of any type, parsed from a style-spec layer object.
AnySource: A style source of any type, parsed from a style-spec source object.
FsResponse: Return value for a resource request callback.
GeoJsonError: Error returned when creating a MapLibre Native GeoJSON value.
LineCap: Line cap type.
LineJoin: Line join type.
MapLoadErrorKind: Error kind reported while loading a map or style.
RenderingError: Errors that can occur during map rendering operations.
SourceRefMut: A mutable reference to a source owned by the current style.
SourceType: MapLibre style-spec source type.
StyleError: Error returned by style operations.
SymbolAnchor: Symbol icon anchor point.

Traits§

Layer: A style layer type that can be added to a StyleRef.
Source: A style source type that can be added to a StyleRef.

Functions§

register_file_source_callback: Install a Rust closure as the ResourceLoader file-source callback for every subsequently constructed mbgl::Map.
set_log_thread_enabled: Enable or disable the internal logging thread