Introduction

maplibre-rs is a portable and performant vector maps renderer.

Supported Platforms

For development the following platforms are recommended:

• Linux X11/Wayland
• MacOS
• Latest Firefox Nightly/Chrome Canary with WebGPU (Because WebGPU is a living spec, sometimes a bleeding-edge browser release is required)

Short-term Obstacles

Long-term Goals

WebGPU is not enabled by default for all platforms.

WebGPU Status:

• Firefox
• Chrome
• WebKit

✅ = First Class Support — 🆗= Best Effort Support — 🛠️ = Unsupported, but support in progress

Developer Log

I'm regularly releasing blog posts on my blog.

User Guide

Development Guide

Building

Debugging

• log crate

GPU Debugging

• For WebGL there is SpectorJS is enabled by default right now. For debugging on a desktop environment you can use RenderDoc.

Frame Profiling

• tracing crate

Development Documents

Architecture

Rendering Architecture

The big picture of wgpu is as follows:

A simplified version is shown below:

Notes:

• wgpu is able to create an interface through which we can reach any device with a GPU.

OS Architecture

Notes:

• The ability to use shared memory or the atomic instruction set of WASM comes by enabling compilation features.
• threads support here does not introduce threads like we know them from Linux. It introduces
• support for atomics like specified in a working draft to WebAssembly. Threads are simulated using WebWorkers by the browser.

Design

Caching

The caching for maplibre-rs is handled on the networking layer. This means that data which is fetched over slow IO is cached in the format of the network requests. The maplibre-rs library is not introducing a separate serialization format for caching.

Instead, caching functionality of HTTP client libraries of the web platform are used. This has the advantage that we can honor HTTP headers which configure caching. This is very important for fetched tiles, as they can have an expiry date.

• On the web the browser is automatically caching raw tiles.
• On Linux, MacOs, iOS and Android we are utilizing reqwest-middleware-cache, which writes raw network requests to disk.

Stencil Masking

The following diagram shows a method which has been used in the beginning of maplibre-rs. It is not used currently.

Font Rendering

There exists no universally perfect solution to font rendering. Depending on the runtime environment a method needs to be chosen. This StackOverflow post outlines some state-of-the-art methods. Some more approaches are described here.

From my perspective the following approaches could work potentially:

1. Tessellate Fonts
2. SDF Font Rendering
3. GPU Text Rendering directly from Bezier Curves
4. Draw text using a Web Canvas and load them to GPU

There is a thesis which summarizes some methods here. A link collection about font related projects can be viewed here.

Approaches

Tessellate Fonts

There is ttf2mesh which generates meshes. I was already able to generate about 1k glyphs with ~40FPS.

SDF Font Rendering

There is a blogpost by Mapbox here. Some more implementation documents are available here. A good foundation for SDF fonts was created by Chlumsky with msdfgen.

GPU Text Rendering from Bezier Curves

The solutions exist:

• By Will Dobbie with an implementation here
• Slug Library which is patented and probably therefore not usable

Here is the whitepaper of the Slug library. There is also a poster about it. There also exists an open implementation.

Draw text using a Web Canvas

This approach has the downside that we can not dynamically scale rendered fonts according to the current zoom level.

Other Approaches

• 16x AA font rendering using coverage masks

Library Packaging

Apple

On Apple maplibre-rs is packaged as:

• Multiple .xcarchive packages which include a framework. Each for a different architecture and platform.
• A single .xcframework package which contains multiple frameworks of different architectures and platforms.
• A swift package which just references the .xcframework package and makes distributing easier.

The following diffs are extracted from this diff. They should serve as documentation for the XCode project. This is required because XCode is a mess.

XCode Project description

Library Entry

The swift code above is the main entry for the Swift API. From this entry file we can expose more API of maplibre-rs. Any C functions which are referenced in the XCode framework's header are available automatically in Swift.

Framework

The framework needs to link against the static library libmaplibre_apple.a, which has been generated by Cargo. In order to allow XCode to dynamically select the library based on the Library Search Path (Build Settings) one needs to add a relative file to XCode. The entry in the project.pbxproj should look like that:

B085D5A32812987B00906D21 /* libmaplibre_apple.a */ = {
    isa = PBXFileReference;
    lastKnownFileType = archive.ar;
    path = libmaplibre_apple.a;
    sourceTree = SOURCE_ROOT;
};

Note the path = libmaplibre_apple.a. This path does not link to a concrete file, but to a file which can be found during building.

A file can be added to the frameworks and library link phase in XCode.

Cargo Build Phase

In order to trigger Cargo builds when starting a XCode build we include a Cargo Build script. This build script needs to run before the linking phase (drag and drop it to the top).

The following build script builds based on XCode environment variables the correct static library. We depend on the $ARCHS environment variable, as the others seem unreliable. Note that this can include multiple architectures, unless the build setting ONLY_ACTIVE_ARCH is set to YES.

arch="unknown"
vendor="apple"
os_type="unknown"
environment_type=""

mode=""

echo "ARCH: $ARCHS"

if [[ $CONFIGURATION == "Release" ]]
then
    mode="--release"
fi

if [[ $ARCHS == "x86_64" ]]
then
    arch="x86_64"
elif [[ $ARCHS == "arm64" ]]
then
    arch="aarch64"
fi

if [[ $SDK_NAME == *"iphoneos"* ]]
then
    os_type="ios"
elif [[ $SDK_NAME == *"macos"* ]]
then
    os_type="darwin"
elif [[ $SDK_NAME == *"iphonesimulator"* ]]
then
    os_type="ios"
    if [[ $ARCHS == "arm64" ]]
    then
        environment_type="sim"
    fi
fi


triplet="$arch-$vendor-$os_type"

if [ -n "$environment_type" ]
then
    triplet="$triplet-$environment_type"
fi

echo "Mode: $mode"
echo "Triplet: $triplet"
echo "Shell: $SHELL"

cmd="export HOME=$HOME && . $HOME/.cargo/env && cargo build -p apple $mode --target $triplet --lib"

echo "Command: $cmd"

env -i /bin/bash -c "$cmd"

Build Settings

Explanations for the settings:

• BUILD_LIBRARY_FOR_DISTRIBUTION: Define that this is a library (effect unknown to me)
• CODE_SIGN_STYLE: The framework is not signed
• DEVELOPMENT_TEAM: No development team is set
• LIBRARY_SEARCH_PATHS[sdk=x][arch=y]: We set the path for the libmaplibre_apple.a lies
• MACH_O_TYPE / SKIP_INSTALL: If this is not set to staticlib and NO, then the libmaplibre_apple.a binary is not included in the final framework xcarchive.
• SUPPORTED_PLATFORMS: Explicitly says that this library works on any platform.
• SUPPORTS_MACCATALYST: Explicitly says that this library works on Mac Catalyst.

The same settings are done for Release and Debug.

xcframework packaging

Creating a xcframework is usually quite straight forward. Just execute the following:

xargs xcodebuild -create-xcframework -framework ./a -framework ./b -output out.xcframework

Unfortunately, it is not possible to bundle some frameworks together like:

• macOS-arm64 and macOS-x86_64

In order to package these architectures and platforms together a fat binary needs to be created using the lipo tool. This means from two frameworks we create a unified framework with a fat binary. There are two important steps:

1. Create a fat binary using lipo -create binA binB -output binfat
2. Copy for example the arm64 framework and add the .swiftmodule definitions from the x86_64 framework

Single UIApplication

Right now winit only allows the usage of a UIApplication. This means the application needs to run in fullscreen. Tracking Issue

Example App

The following settings are important for the example application within the XCode project.

Info Plist for Applications

• The INFOPLIST_KEY_UIApplicationSceneManifest_Generation needs to be unset. Else the application screen is just black.

Files & Assets

• The example/demo application within the XCode project references the maplibre_rs.framework. Some default files have been removed.

MacOS Entitlements

• On macOS one needs to allow network access via com.apple.security.network.client

Android

Gradle Project Setup

In order to package an Android .aar archive we use the rust-android-gradle. Except some customisations for the latest NDK toolchain release everything worked flawlessly.

JNI

There is no way right now to automatically generate JNI stubs for Rust. A manual example is available in the android crate of maplibre-rs.

Single NativeActivity

Right now winit only allows the usage of a NativeActivity. This means the application needs to run in fullscreen. This native activity is referenced in the ´AndroidManifest.xml` by defining the name of the shared library. Tracking Issue

Web

This document describes issues and challenges when packaging maplibre-rs as a npm package.

Required Formats

ESM

The ESM module format is the standard nowadays which should be followed. If a JS bundler encounters an ESM module it can resolve WebAssembly files or WebWorkers dynamically. The following syntax is used to resolve referenced WebWorkers:

new Worker(new URL("./pool.worker.ts", import.meta.url), {
    type: 'module'
});

Similarly, the following works:

new URL('index_bg.wasm', import.meta.url);

IIFE (immediately-invoked function expression)

This format is used when including maplibre-rs in a <script> tag. The library is "written" onto the window/global object. This allows quick prototyping/playgrounds/experiments using maplibre-rs.

In order to support this we need to create a bundle which works on any modern browser. Additionally, a WASM file and WebWorker needs to be deployed at a predictable path, because there is no bundler active which manages assets. Users of these libraries have to specify where WASM or non-inlined WebWorkers are located.

Both assets could be inlined theoretically. This is common for WebWorkers, but not for WASM files.

UMD

UMD modules are needed when creating a library which should run in Node as well as browsers. This is not a usecase for maplibre-rs. If we support node, then we probably would ship a separate package called "maplibre-rs-node" which bundles to CJS directly.

CJS/CommonJS

Not needed for the browser build of maplibre-rs, possibly needed when supporting Node

With a CommonJS module its is not possible for bundlers to dynamically resolve WebWorkers or WASM files.

The import.meta.url token can not exist in a CommonJS module. Therefore, bundlers which encounter a CommonJS module have to use a different mechanism of resolving files.

Generally, we do not need to support CommonJS, because we are not targeting Node with maplibre-rs. It's properly good to support it as a fallback though, for bundlers which can not deal with ESM modules yet. This is for example true for test runners like Jest which require that dependencies are available as CJS module.

wasm-pack output

wasm-pack can output multiple formats. The web and bundler outputs offer the most modular modules. Unfortunately, the function wasm_bindgen::module() is only supported in web and no-modules. We currently are using this in order to send loaded instances of WebAssembly.Module to WebWorkers. nodejs should not be used because MapLibre does not target Node. Therefore, we should stick to the web output format.

Required Features

• WASM Bundling: Make the WASM binary available to users of the maplibre-rs library
• WebWorker Bundling: Make the WebWorker available to users of the maplibre-rs library. This could also be achived by inlining.
• WebWorker Inlining: Inline the WebWorker bundle in the library bundle as a string.
• Predictable Paths: Without predictable paths, it's difficult for users to reference the wasm file directly from the node_modules directory if requried.

Bundler Feature Comparison

Features in italics are required for maplibre-rs.

1. Technically not a bundler but can be used to emit ES modules
2. Was Supported in Webpack 4, but currently is not supported
3. https://github.com/parcel-bundler/parcel/issues/8004
4. As of the time of writing Webpack can not output ESM libraries
5. Plugins exist, but they don't work reliably
6. Plugins exist, and work reliably

ESBuild

ESBuild supports CJS, ESM and IIFI modules equally well. Plugins exist for WebWorker inlining and resolving assets through import.meta.url. The plugin quality seems to be superior compared to Parcel. It is also very fast compared to all other bundlers.

• IIFI: The esbuild bundler translates to new URL('index_bg.wasm', import.meta.url); to

  var __currentScriptUrl__ = document.currentScript && document.currentScript.src || document.baseURI;
  new URL("./assets/index_bg.wasm?emit=file", __currentScriptUrl__);
  

See config in web/lib/build.mjs for an example usage.

Babel & TypeScript

Babel and TypeScript both can produce ESM modules, but they fail with transforming references within the source code like new URL("./pool.worker.ts", import.meta.url). There exist some Babel plugins, but none of them is stable. Therefore, we actually need a proper bundler which supports outputting ESM modules. The only stable solution to this is Parcel. Parcel also has good documentation around the bundling of WebWorkers.

WebPack

WebPack supports older module formats like CommonJS or UMD very well. It falls short when bundling the format ESM format which is not yet stable. It also does not support inlining WebWorkers in version 5. The wasm-pack plugin for WebPack makes including Cargo projects easy.

• CJS: Webpack translates new URL('index_bg.wasm', import.meta.url); to something that is equivalent to './index_bg.wasm' . It just expects that assets are resolvable from the current file.

Example scripts for package.json:

{
  "scripts": {
    "webpack": "webpack --mode=development",
    "webpack-webgl": "npm run build -- --env webgl",
    "webpack-production": "webpack --mode=production",
    "webpack-webgl-production": "npm run production-build -- --env webgl"
  }
}

Example config:

const path = require("path");
const webpack = require("webpack");
const WasmPackPlugin = require("@wasm-tool/wasm-pack-plugin");

let dist = path.join(__dirname, 'dist/maplibre-rs');
module.exports = (env) => ({
    mode: "development",
    entry: "./src/index.ts",
    experiments: {
        syncWebAssembly: true,
    },
    performance: {
        maxEntrypointSize: 400000,
        maxAssetSize: 400000000,
    },
    output: {
        path: dist,
        filename: "maplibre-rs.js",
        library: {
            name: 'maplibre_rs',
            type: 'umd',
        },
    },
    module: {
        rules: [
            {
                test: /\.ts$/,
                exclude: /node_modules/,
                use: [
                    {
                        loader: 'ts-loader',
                        options: {}
                    }
                ]
            },
        ],
    },
    resolve: {
        extensions: ['.ts', '.js'],
    },
    plugins: [
        new webpack.DefinePlugin({
            'process.env.WEBGL': !!env.webgl
        }),
        new WasmPackPlugin({
            crateDirectory: path.resolve(__dirname, '../'),

            // Check https://rustwasm.github.io/wasm-pack/book/commands/build.html for
            // the available set of arguments.
            //
            // Optional space delimited arguments to appear before the wasm-pack
            // command. Default arguments are `--verbose`.
            //args: '--log-level warn',
            // Default arguments are `--typescript --target browser --mode normal`.
            extraArgs: ` --target web -- . -Z build-std=std,panic_abort ${env.webgl ? '--features web-webgl' : ''} ${env.tracing ? '--features trace' : ''}`,

            // Optional array of absolute paths to directories, changes to which
            // will trigger the build.
            // watchDirectories: [
            //   path.resolve(__dirname, "another-crate/src")
            // ],

            // The same as the `--out-dir` option for `wasm-pack`
            outDir: path.resolve(__dirname, 'src/wasm-pack'),

            // The same as the `--out-name` option for `wasm-pack`
            // outName: "index",

            // If defined, `forceWatch` will force activate/deactivate watch mode for
            // `.rs` files.
            //
            // The default (not set) aligns watch mode for `.rs` files to Webpack's
            // watch mode.
            // forceWatch: true,

            // If defined, `forceMode` will force the compilation mode for `wasm-pack`
            //
            // Possible values are `development` and `production`.
            //
            // the mode `development` makes `wasm-pack` build in `debug` mode.
            // the mode `production` makes `wasm-pack` build in `release` mode.
            // forceMode: "production",

            // Controls plugin output verbosity, either 'info' or 'error'.
            // Defaults to 'info'.
            // pluginLogLevel: 'info'
        }),
    ]
});

Parcel

Parcel supports CommonJS and ESM modules equally good. The documentation about import.meta.url is very good. In other bundlers documentations around this feature is missing. In the latest Parcel version inlining WebWorkers is not working.

• CJS: The Parcel bundler translates to new URL('index_bg.wasm', import.meta.url); to new URL("index_bg.wasm", "file:" + __filename); While depending on file: and filename works for NodeJS, it is unsupported in the browser.

Example scripts for package.json:

{
  "scripts": {
    "parcel": "npm run clean && npm run wasm-pack && WEBGL=false parcel build --no-cache src/index.ts",
    "parcel-webgl": "npm run clean && FEATURES=web-webgl npm run wasm-pack && WEBGL=true parcel build --no-cache src/index.ts"
  }
}

Example config in `package.json:

{
  "module": "dist/parcel-esm/module.js",
  "main": "dist/parcel-cjs/main.js",
  "types": "dist/parcel/types.d.ts",
  "targets": {
    "main": {
      "distDir": "./dist/parcel-cjs",
      "context": "browser",
      "outputFormat": "commonjs"
    },
    "module": {
      "distDir": "./dist/parcel-esm",
      "context": "browser",
      "outputFormat": "esmodule"
    }
  },
  "@parcel/transformer-js": {
    "inlineFS": false,
    "inlineEnvironment": [
      "WEBGL"
    ]
  }
}

Rollup

Not yet evaluated

Appendix

Goals

Next Major Goals

• Improve buffer_pool eviction rules
• Use MPI: https://doc.rust-lang.org/book/ch16-02-message-passing.html
• Input-handling via events and functional pipelines
• Show old tiles until new tile is ready / Show mixed tiles, based on availability
• Use a simple style definition
  • type: background/fill/line
  • minzoom/maxzoom
  • source
  • source-layer
  • paint (fill-color)
• Map feeling:
  • Wrap world around in x direction
  • Limit panning in y direction
  • Nicer default map style

Intermediate Goals

• Support multiple projections? PoC such that we are sure the renderer is acceptable

Future Goals

• Very simple text rendering
• Cache tessellation results
  • We have three "caches": downloaded tiles, tessellated tiles, gpu tiles
• Handle missing tiles
• Support different tile raster addressing

Future Ideas

• Use rust-gpu as shading language
• Focus on accessibility of maps: https://www.w3.org/WAI/RD/wiki/Accessible_Maps
• Display in AR: https://developer.apple.com/documentation/arkit/displaying_an_ar_experience_with_metal
• Use tracing framework: tracing

Challenges:

• Accuracy of floating point numbers is very bad for big world view coordinates (Plot)
• Perils of World Space

Create paths for tessellating streets

Streets can have unusual shaped like shown here in Munich. OSM does not offer such data and therefore just renders an ordinary street contour like shown here. Because the data is probably not available this is a very hard challenge.

Related Resources

Talks

• 2022-04-13-World-in-Vectors

Related Projects

• Tangram Renderer
• Tilezen/Nextzen
• Protomaps: New Maps Stack
• Harp GL

GIS

• Google Maps Projection
• Grid Calculation Examples
• Slippy map tilenames (also known as XYZ)
• TMS
• Mapbox Adaptive Projections
• Bing Map Tile System
• Bing: Understanding Scale and Resolution

WebAssembly and WebWorkers

Specs:

• Thread/Atomics Proposal for WASM

Projects:

• Experiment with shared memory and the idea behind it
• Shared channel
• Bridge for async executors
• Rayon for WebAssembly
• wasm-mt: postMessage message passing

Articles:

• WebAssembly Threads (official)
• Multithreading Rust and Wasm 2018
• postMessage Performance
• A practical guide to WebAssembly memory

Examples:

• WASM in a WebWorker
• Building for Shared Memory
• Parallel Raytracing

Rendering

Specs:

• WebGPU Spec
• WGSL Spec
• WGSL Struct Alignment
• Mismatches Stencil Test

Articles:

• Life of a Tile (MapLibre)

Tutorials:

• Stencil Testing
• Camera
• Writing an efficient Vulkan renderer

Examples:

• Stencil Mask Example
• WGPU Examples

Maths

Articles:

• Magnificent Matrix

Examples:

• Dolly Camera

Font Rendering

Specs:

• MapBox Glyphs Spec

Articles:

• Signed distance function

Projects:

• Mapbox fontnik
• TinySDK (JS)
• RustType
• SDF Render
• pbf_font_tools
• Multi-channel signed distance field generator
  • MSDF font atlas generator

Tessellation

Projects:

• earcutr
• Line Tessellation in MapLibre

Specifications

• TileJSON

Render Graphs

• https://github.com/metal-by-example/simple-instancing/blob/master/MetalSimpleInstancing/Renderer.swift
• https://github.com/troughton/Substrate
• https://de.slideshare.net/DICEStudio/framegraph-extensible-rendering-architecture-in-frostbite
• http://themaister.net/blog/2017/08/15/render-graphs-and-vulkan-a-deep-dive/
• http://themaister.net/blog/2017/08/15/render-graphs-and-vulkan-a-deep-dive/

Animation

• https://crates.io/crates/pareen
• https://crates.io/crates/keyframe