fast-layer 0.1.1

WIP: A fast WebAssembly-based layer for high-performance MapLibre/Mapbox
Documentation

Fast Layer

A fast WebAssembly-based layer for high-performance MapLibre/Mapbox rendering using WebGL2.

WebAssembly Rust WebGL2 License: MIT

🚧 Status: Work In Progress

This project is currently in development and is not ready for production use. Features are being actively developed and the API may change.

Overview

Fast Layer is a WebAssembly (WASM) library written in Rust that provides high-performance map rendering capabilities by leveraging WebGL2. It's designed to integrate seamlessly with MapLibre GL JS and Mapbox GL JS, offering improved performance for complex map visualizations.

Key Features

  • ⚡ High Performance: WebGL2-accelerated rendering for smooth map interactions
  • 🦀 Rust + WebAssembly: Memory-safe, blazing-fast WebAssembly compilation
  • 🗺️ MapLibre Compatible: Seamless integration with MapLibre GL JS
  • 🔧 Custom Shaders: Vertex and fragment shader support for advanced rendering effects
  • 📱 Cross-Platform: Works in all modern browsers supporting WebGL2

Technology Stack

  • Rust: Primary language for WASM compilation
  • WebAssembly (WASM): High-performance web deployment
  • WebGL2: Advanced graphics rendering
  • MapLibre GL JS: Map rendering library
  • wasm-bindgen: Rust-WebAssembly interoperability
  • web-sys: Web API bindings for Rust

Quick Start

Prerequisites

  • Rust (latest stable version)
  • wasm-pack (WebAssembly packaging tool)
  • A modern web browser with WebGL2 support

Installation

  1. Clone the repository:
git clone https://github.com/username/fast-layer.git
cd fast-layer
  1. Build the WebAssembly module:
chmod +x build.sh
./build.sh

The build script will:

  • Install wasm-pack if not already installed
  • Compile Rust to WebAssembly
  • Generate JavaScript bindings
  • Output files to www/pkg/

Running the Demo

  1. Open www/index.html in a web browser
  2. The demo will load MapLibre with a basic FastLayer implementation
  3. You should see a map with a red point rendered by the WebGL2 layer

Project Structure

fast-layer/
├── src/
│   ├── lib.rs          # Main WASM library implementation
│   └── main.rs         # Test/development binary
├── www/
│   ├── index.html      # Demo webpage
│   ├── map.js          # MapLibre integration
│   └── pkg/            # Generated WASM package (after build)
├── build.sh            # Build script
├── Cargo.toml          # Rust dependencies and configuration
└── README.md           # This file

API Reference

FastLayer Struct

#[wasm_bindgen]
pub struct FastLayer {
    canvas_id: String,
    context: WebGl2RenderingContext,
    program: Option<WebGlProgram>,
}

Methods

  • new(canvas_id: &str) -> FastLayer: Creates a new FastLayer instance
  • compile(&mut self): Compiles the WebGL2 shaders and links the program
  • draw(&self, matrix: &[f64]): Renders the layer using the provided transformation matrix

Usage Example

import { FastLayer } from "./pkg/fast_layer.js";

// Initialize the WASM module
await init();

// Create a new FastLayer instance
const fastLayer = new FastLayer("canvas-id");

// Compile shaders
fastLayer.compile();

// Draw with transformation matrix
const matrix = [1.0, 0.0, 0.0, 1.0];
fastLayer.draw(matrix);

Development

Building from Source

# Install wasm-pack if not already installed
curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh

# Build the project
wasm-pack build --target web --out-dir www/pkg

Running Tests

cargo test

Development Server

For development, you can serve the www/ directory with any static file server:

# Using Python
python -m http.server 8000

# Using Node.js (if you have serve installed)
npx serve www

# Using PHP
php -S localhost:8000 -t www/

Then open http://localhost:8000 in your browser.

Performance

Fast Layer is designed to provide superior performance compared to JavaScript-based map layers by:

  • Running compute-intensive operations in optimized WebAssembly
  • Utilizing low-level WebGL2 APIs for maximum GPU utilization
  • Minimizing JavaScript-WebAssembly boundary crossings
  • Leveraging Rust's zero-cost abstractions

Browser Compatibility

  • Chrome 56+ (WebGL2 support)
  • Firefox 51+ (WebGL2 support)
  • Safari 15+ (WebGL2 support)
  • Edge 79+ (WebGL2 support)

Contributing

This project is in early development. Contributions are welcome!

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature-name
  3. Make your changes
  4. Test thoroughly
  5. Submit a pull request

Development Guidelines

  • Follow Rust naming conventions
  • Add tests for new functionality
  • Update documentation as needed
  • Ensure WebGL2 compatibility

Roadmap

  • Complete shader pipeline implementation
  • Add support for complex geometries
  • Implement efficient data streaming
  • Add animation and transition support
  • Optimize memory usage
  • Add comprehensive test suite
  • Performance benchmarking
  • Documentation improvements

License

This project is licensed under the MIT License - see the LICENSE.txt file for details.

Author

Sebastian Oscar Lopez - sebastianoscarlopez@gmail.com

Acknowledgments

Support

For questions, issues, or contributions, please visit the GitHub repository or contact the author directly.

Note: This is a work-in-progress project. APIs and functionality may change significantly before the first stable release.