Designing a High‑Performance WebGL Map Engine: Architecture & Rendering Core

Today we discuss the architecture of a WebGL map engine and the design of its rendering core. Earlier versions of web maps used DOM or Canvas2D; this article focuses only on the WebGL‑related parts.

Functional components of a WebGL map engine

Data request, parsing, and cache management.

WebGL shader and state management.

Creation and management of various buffers and texture objects.

Rendering of different element types.

Design considerations

Modules should be decoupled to facilitate collaborative development.

High performance achieved through architectural solutions.

Efficiency by encapsulating low‑level details.

WebGL rendering engine architecture

The overall architecture is illustrated below:

Main module descriptions

Map is the core class representing the map itself; it creates managers such as Scene, LayerManager, and OverlayManager during initialization.

Scene is the rendering core logic, creating a render loop (described later).

LayerManager calculates the grid data needed for the current viewport and notifies each Layer to load data.

Layer sends requests via a Worker; the Worker parses the data and returns it, all managed by WorkerManager.

Features store data for the current viewport; the Painter class retrieves this data for drawing, allowing request/parse and drawing to be fully decoupled.

Painter references several WebGL‑related modules: WebGLProgram manages shaders, Draw Utils provides drawing functions for various element types, TextureAtlas handles dynamic texture atlasing, and Camera performs view‑matrix calculations. These modules encapsulate low‑level WebGL calls to improve development efficiency.

Core rendering logic

The Scene module implements the core rendering logic and listens to Map state change events:

center_change – triggered when the map center changes.

zoom_change – triggered when the zoom level changes.

heading_change – triggered when the north direction changes.

tilt_change – triggered when the tilt angle changes.

When an event is received, Scene starts an animation loop using requestAnimationFrame (rAF) and ensures only one rAF loop runs. The loop automatically stops after 100 ms of inactivity and restarts on the next event.

function draw(currentTime) {
    // Request a new call to draw the next frame before you actually
    // start drawing the current frame.
    requestAnimationFrame(draw);
    // Update the position of the moving objects in your scene

    // Draw your scene
}

function startup() {
    // Do your usual setup and initialization
    draw();
}

Another example from the ThreeJS documentation:

function render() {
    requestAnimationFrame(render);
    renderer.render(scene, camera);
}
render();

Using rAF for continuous rendering can waste resources if the scene is static, especially on mobile devices where it increases power consumption. Moreover, iOS does not allow background access to OpenGL, causing the app to be terminated when sent to the background. Therefore, in practice the render loop is started on demand and stops automatically when no state changes occur.

From another perspective, frequent Map events can be synchronized to the rAF frame, ensuring smooth rendering regardless of event frequency, a strategy applicable to other interactive interfaces.