Introduction

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

Name

The name of the library is "maplibre-rs". The camel-case version of it is "MapLibreRs".

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

Running maplibre-rs demos on various platforms

During development, you will want to run the maplibre demos on your local machine to test out your changes. There are multiple demos of maplibre-rs for different targets. Some targets have prerequisites depending on your operating system.

• maplibre-demo - targets Windows, macOS and Linux, it is built directly with cargo.
• apple - targets iOS and macOS and relies on the xcode IDE.
• android - targets Android devices and builds in Android Studio.
• web - targets the web using a WASM binary.
• maplibre-headless - TBD

All the targets below require you to install rustup to manage your Rust toolchain.

Note: Make sure you have selected the right toolchain target within rustup. You can use rustup show to see your active toolchain. If you want to change the target of the build manually, use the cargo --target parameter.

Maplibre-demo

Linux/macOS

The build for desktop is very simple, you just have to run the following command from the root of the maplibre-rs project:

cargo run -p maplibre-demo

Windows

Windows has two additional prerequisites to be able to run. You will need CMake, Visual Studio C++ build tools and the sqlite3 library.

Install CMake and add it to your path environment variables.

For the C++ build tools, download the Visual Studio 2022 Build tools from the Microsoft website. After the download, while installing the Build tools, make sure that you select the C++ build tools.

To install sqlite3 you need to build the sqlite3.lib manually with the following steps. This will generate a .lib file that you will have to add to the SQLITE3_LIB_DIR environment variable.

Restart your shell to make sure you are using up-to-date environment variables.

Finally, the command below should execute successfully:

cargo run -p maplibre-demo

Android

Start by installing the Android Studio IDE.

Make sure the NDK is installed. The Native Development Kit (NDK) is a set of tools that allows you to use C and C++ code with Android. You have to install manually the version that is used in ./android/gradle/lib/build.gradle.

ANDROID STUDIO -> tools -> SDK manager -> SDK tools -> tick show package details -> ndk (side by side)

Open the project within ./android/gradle and create a new virtual device with the device manager. Minimum SDK version should be 21. This was tested on an x86_64 emulator. Finally, run the demo configuration. It should open your virtual device and run the maplibre-rs Android demo on it. Alternatively you can also run it on your own Android device.

Note: If you are building for an x86 Android device, you probably need to install the following target using
rustup with the following command rustup target add i686-linux-android.

Note: Android is configured to support OpenGL ES 3.1 (This API specification is supported by Android 5.0 (API level 21) and higher). Your Android device is required to support OpenGL ES 3.1 at least. There are some issues here and here that discuss configuration of Android Studio for OpenGL ES 3.1 support in emulators.

Apple

Apple builds rely on the XCode IDE. Start by installing XCode and open the project within ./apple/xcode.

Cargo is used in to build the maplibre library in the build phases of the XCode project configuration.

iOS

You can use XCode to run on a iOS Simulator or a real device. Install a simulator in XCode. Version 9 is the minimum version supported theoretically.

Select the scheme called example (iOS) and click on run. This will start the iOS application.

macOS

As you might have seen in the maplibre-demo section, you can build Unix executables directly with Cargo. In order to build a proper macOS application (in OSX terminology) you have to use the ./apple/xcode project.

Open the project from the folder ./apple/xcode with XCode. Select the scheme called example (macOS) and click on run. This will start the macOS application.

The minimum target OSX version for the macOS build is defined inside Build settings -> Deployment -> macOS deployment target. If you are using a lower version of OSX, you will not be able to run the application on your computer.

Web (WebGL, WebGPU)

You need to first build the library for WebGL or WebGPU. Optionally, you can also enabled multi-threading support, which requires that the library is used in a secure environment: isSecureContext and crossOriginIsolated. The demo runs this such an environment.

If you have a browser which already supports a recent version of the WebGPU specification then you can build the library with WebGPU:

just web-lib build # WebGPU

If not, then you must enable WebGL support:

just web-lib build --webgl # WebGL
just web-lib build --webgl --multithreaded # WebGL + multithreaded

Instead of building it is also possible to watch for changes. The same flags as with web-lib build are supported:

just web-lib watch --webgl

After building the library you can run the demo server:

just web-demo start

Building Libraries

TODO

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

maplibre-rs is set up to use the Tracy profiler (https://github.com/wolfpld/tracy). It's mainly designed for C++ but has some Rust support.

The connection to Rust uses a project that connects to the tracing crate (https://github.com/nagisa/rust_tracy_client). This uses a set of three crates (tracing-tracy, tracy-client, tracy-client-sys).

Unfortunately, the Tracy project does not use semantic versioning, whereas tracing-tracy, tracy-client, tracy-client sys do.

The current version of the Rust client is at v0.8.1 of Tracy. See the correlating versions in the table below (original at https://github.com/nagisa/rust_tracy_client#version-support-table):

Development Documents

Architecture

Rendering Architecture

The big picture of wgpu is as follows:

A simplified version is shown below:

A further simplified version:

Notes:

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

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

Domain Model

Data Model

Crate and Project Structure

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("./multithreaded-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 use case 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("./multithreaded-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

• Start Date: 2022-10-29
• RFC PR: maplibre/maplibre-rs#??
• maplibre-rs Issue: N/A

Summary

The "RFC" (request for comments) process is intended to provide a consistent and controlled path for new features to enter the map renderer and standard libraries, so that all stakeholders can be confident about the direction the map renderer is evolving in.

This RFC is copied from rust-lang/rfcs. Thanks to everyone who contributed to the Rust RFC process RFC! Thanks for the great inspiration!

Motivation

The freewheeling way that we add new features to maplibre-rs has been good for early development, but for maplibre-rs to become a mature platform we need to develop some more self-discipline when it comes to changing the system. This is a proposal for a more principled RFC process to make it a more integral part of the overall development process, and one that is followed consistently to introduce features to maplibre-rs.

Detailed design

Many changes, including bug fixes and documentation improvements can be implemented and reviewed via the normal GitHub pull request workflow.

Some changes though are "substantial", and we ask that these be put through a bit of a design process and produce a consensus among the maplibre-rs community.

When you need to follow this process

You need to follow this process if you intend to make "substantial" changes to the maplibre-rs distribution. What constitutes a "substantial" change is evolving based on community norms, but may include the following.

• Any semantic or syntactic change to the map renderer that is not a bugfix.
• Removing map renderer features, including those that are feature-gated.

Some changes do not require an RFC:

• Rephrasing, reorganizing, refactoring, or otherwise "changing shape does not change meaning".
• Additions that strictly improve objective, numerical quality criteria (warning removal, speedup, better platform coverage, more parallelism, trap more errors, etc.)
• Additions only likely to be noticed by other developers-of-maplibre-rs, invisible to users-of-maplibre-rs.

If you submit a pull request to implement a new feature without going through the RFC process, it may be closed with a polite request to submit an RFC first.

What the process is

In short, to get a major feature added to maplibre-rs, one must first get the RFC merged into the RFC repo as a markdown file. At that point the RFC is 'active' and may be implemented with the goal of eventual inclusion into maplibre-rs.

• Fork the repo https://github.com/maplibre/maplibre-rs
• Copy rfc/0000-template.md to rfc/0000-my-feature.md (where 'my-feature' is descriptive. don't assign an RFC number yet).
• Fill in the RFC
• Submit a pull request. The pull request is the time to get review of the design from the larger community.
• Build consensus and integrate feedback. RFCs that have broad support are much more likely to make progress than those that don't receive any comments.

Eventually, somebody on the maplibre-rs team will either accept the RFC by merging the pull request, at which point the RFC is 'active', or reject it by closing the pull request.

Who ever merges the RFC should do the following:

• Assign an id, using the PR number of the RFC pull request. (If the RFC has multiple pull requests associated with it, choose one PR number, preferably the minimal one.)
• Add the file in the docs/src/rfc/ directory.
• Create a corresponding issue on maplibre-rs repo
• Fill in the remaining metadata in the RFC header, including links for the original pull request(s) and the newly created maplibre-rs issue.
• Communicate that given RFC is now considered 'active' on the chat platform of maplibre-rs.
• Commit everything.

Once an RFC becomes active then authors may implement it and submit the feature as a pull request to the maplibre-rs repo. An 'active' is not a rubber stamp, and in particular still does not mean the feature will ultimately be merged; it does mean that in principle all the major stakeholders have agreed to the feature and are amenable to merging it.

Modifications to active RFC's can be done in followup PR's. An RFC that makes it through the entire process to implementation is considered 'complete'; an RFC that fails after becoming active is 'inactive'.

Alternatives

Retain the current informal RFC process. The newly proposed RFC process is designed to improve over the informal process in the following ways:

• Discourage non-actionable or vague RFCs
• Ensure that all serious RFCs are considered equally
• Give confidence to those with a stake in maplibre-rs development that they understand why new features are being merged

As an alternative, we could adopt an even stricter RFC process than the one proposed here. If desired, we should likely look to Python's PEP process for inspiration.

Unresolved questions

1. Does this RFC strike a favorable balance between formality and agility?
2. Does this RFC successfully address the aforementioned issues with the current informal RFC process?
3. Should we retain rejected RFCs in the archive?

• Feature Name: (fill me in with a unique ident, my_awesome_feature)
• Start Date: (fill me in with today's date, YYYY-MM-DD)
• RFC PR: maplibre/maplibre-rs#0000
• maplibre-rs Issue: maplibre/maplibre-rs#0000

Summary

One paragraph explanation of the feature.

Motivation

Why are we doing this? What use cases does it support? What is the expected outcome?

Guide-level explanation

Explain the proposal as if it was already included in the project, and you were teaching it to another maplibre-rs user. That generally means:

• Introducing new named concepts.
• Explaining the feature largely in terms of examples.
• Explaining how maplibre-rs users should think about the feature, and how it should impact the way they use maplibre-rs. It should explain the impact as concretely as possible.
• If applicable, provide sample error messages, deprecation warnings, or migration guidance.
• If applicable, describe the differences between teaching this to the existing maplibre-rs users and new maplibre-rs users.

For implementation-oriented RFCs (e.g. for internals), this section should focus on how maplibre-rs contributors should think about the change, and give examples of its concrete impact. For policy RFCs, this section should provide an example-driven introduction to the policy, and explain its impact in concrete terms.

Reference-level explanation

This is the technical portion of the RFC. Explain the design in sufficient detail that:

• Its interaction with other features is clear.
• It is reasonably clear how the feature would be implemented.
• Corner cases are dissected by example.

The section should return to the examples given in the previous section, and explain more fully how the detailed proposal makes those examples work.

Drawbacks

Why should we not do this?

Rationale and alternatives

• Why is this design the best in the space of possible designs?
• What other designs have been considered and what is the rationale for not choosing them?
• What is the impact of not doing this?

Prior art

Discuss prior art, both the good and the bad, in relation to this proposal. A few examples of what this can include are:

• Does this feature exist in other map renderers and what experience have their community had?
• For community proposals: Is this done by some other community and what were their experiences with it?
• For other teams: What lessons can we learn from what other communities have done here?
• Papers: Are there any published papers or great posts that discuss this? If you have some relevant papers to refer to, this can serve as a more detailed theoretical background.

This section is intended to encourage you as an author to think about the lessons from other renderers, provide readers of your RFC with a fuller picture. If there is no prior art, that is fine - your ideas are interesting to us whether they are brand new or if it is an adaptation from other map renderers.

Note that while precedent set by other map renderers is some motivation, it does not on its own motivate an RFC.

Unresolved questions

• What parts of the design do you expect to resolve through the RFC process before this gets merged?
• What parts of the design do you expect to resolve through the implementation of this feature before stabilization?
• What related issues do you consider out of scope for this RFC that could be addressed in the future independently of the solution that comes out of this RFC?

Future possibilities

Think about what the natural extension and evolution of your proposal would be and how it would affect the renderer and project as a whole in a holistic way. Try to use this section as a tool to more fully consider all possible interactions with the project and renderer in your proposal. Also consider how this all fits into the roadmap for the project and of the relevant sub-team.

This is also a good place to "dump ideas", if they are out of scope for the RFC you are writing but otherwise related.

If you have tried and cannot think of any future possibilities, you may simply state that you cannot think of anything.

Note that having something written down in the future-possibilities section is not a reason to accept the current or a future RFC; such notes should be in the section on motivation or rationale in this or subsequent RFCs. The section merely provides additional information.

• Start Date: 2022-10-29
• RFC PR: maplibre/maplibre-rs#??
• maplibre-rs Issue: N/A

Summary

The "RFC" (request for comments) process is intended to provide a consistent and controlled path for new features to enter the map renderer and standard libraries, so that all stakeholders can be confident about the direction the map renderer is evolving in.

This RFC is copied from rust-lang/rfcs. Thanks to everyone who contributed to the Rust RFC process RFC! Thanks for the great inspiration!

Motivation

The freewheeling way that we add new features to maplibre-rs has been good for early development, but for maplibre-rs to become a mature platform we need to develop some more self-discipline when it comes to changing the system. This is a proposal for a more principled RFC process to make it a more integral part of the overall development process, and one that is followed consistently to introduce features to maplibre-rs.

Detailed design

Many changes, including bug fixes and documentation improvements can be implemented and reviewed via the normal GitHub pull request workflow.

Some changes though are "substantial", and we ask that these be put through a bit of a design process and produce a consensus among the maplibre-rs community.

When you need to follow this process

You need to follow this process if you intend to make "substantial" changes to the maplibre-rs distribution. What constitutes a "substantial" change is evolving based on community norms, but may include the following.

• Any semantic or syntactic change to the map renderer that is not a bugfix.
• Removing map renderer features, including those that are feature-gated.

Some changes do not require an RFC:

• Rephrasing, reorganizing, refactoring, or otherwise "changing shape does not change meaning".
• Additions that strictly improve objective, numerical quality criteria (warning removal, speedup, better platform coverage, more parallelism, trap more errors, etc.)
• Additions only likely to be noticed by other developers-of-maplibre-rs, invisible to users-of-maplibre-rs.

If you submit a pull request to implement a new feature without going through the RFC process, it may be closed with a polite request to submit an RFC first.

What the process is

In short, to get a major feature added to maplibre-rs, one must first get the RFC merged into the RFC repo as a markdown file. At that point the RFC is 'active' and may be implemented with the goal of eventual inclusion into maplibre-rs.

• Fork the repo https://github.com/maplibre/maplibre-rs
• Copy rfc/0000-template.md to rfc/0000-my-feature.md (where 'my-feature' is descriptive. don't assign an RFC number yet).
• Fill in the RFC
• Submit a pull request. The pull request is the time to get review of the design from the larger community.
• Build consensus and integrate feedback. RFCs that have broad support are much more likely to make progress than those that don't receive any comments.

Eventually, somebody on the maplibre-rs team will either accept the RFC by merging the pull request, at which point the RFC is 'active', or reject it by closing the pull request.

Who ever merges the RFC should do the following:

• Assign an id, using the PR number of the RFC pull request. (If the RFC has multiple pull requests associated with it, choose one PR number, preferably the minimal one.)
• Add the file in the docs/src/rfc/ directory.
• Create a corresponding issue on maplibre-rs repo
• Fill in the remaining metadata in the RFC header, including links for the original pull request(s) and the newly created maplibre-rs issue.
• Communicate that given RFC is now considered 'active' on the chat platform of maplibre-rs.
• Commit everything.

Once an RFC becomes active then authors may implement it and submit the feature as a pull request to the maplibre-rs repo. An 'active' is not a rubber stamp, and in particular still does not mean the feature will ultimately be merged; it does mean that in principle all the major stakeholders have agreed to the feature and are amenable to merging it.

Modifications to active RFC's can be done in followup PR's. An RFC that makes it through the entire process to implementation is considered 'complete'; an RFC that fails after becoming active is 'inactive'.

Alternatives

Retain the current informal RFC process. The newly proposed RFC process is designed to improve over the informal process in the following ways:

• Discourage non-actionable or vague RFCs
• Ensure that all serious RFCs are considered equally
• Give confidence to those with a stake in maplibre-rs development that they understand why new features are being merged

As an alternative, we could adopt an even stricter RFC process than the one proposed here. If desired, we should likely look to Python's PEP process for inspiration.

Unresolved questions

1. Does this RFC strike a favorable balance between formality and agility?
2. Does this RFC successfully address the aforementioned issues with the current informal RFC process?
3. Should we retain rejected RFCs in the archive?