@sakuzu/maplibre-gl-draw 1.0.0

package/dist/view/renderers/polygon/batch.js

@@ -0,0 +1,336 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * PolygonBatchRenderer
+ *
+ * A renderer that draws multiple polygon fills in a single draw call.
+ * By using per-vertex color, polygons of different colors can also be drawn in one go.
+ * The draw order is preserved by the order in which the vertices are laid out.
+ */
+import earcut from 'earcut';
+import { EarcutCache } from '../../cache/earcut.js';
+import { getSurfaceTessellationStep, tessellateSurfaceFill } from '../../globe-subdivision.js';
+import { calculateLngLatOffset, createProgram, getProjectionTransitionUniform, OFFSET_MODE_GLSL, } from '../../shaders/helpers.js';
+import { ProjectionUniformManager } from '../../shaders/projection.js';
+import { TERRAIN_SHADE_FRAGMENT_GLSL, TERRAIN_SHADE_VERTEX_GLSL, } from '../../shaders/terrain-shade.js';
+import { TerrainContext } from '../../terrain/context.js';
+import { TERRAIN_MAX_TILED_COARSEN } from '../../terrain/metrics.js';
+import { batchTessellationFactor, ringBoundingCells } from '../../terrain/polygon.js';
+import { reportTerrainCoarsening } from '../../terrain/state.js';
+import { buildEarcutInput } from './earcut-input.js';
+import { drawFillWithTerrainCull } from './terrain-cull.js';
+/** @internal */
+export class PolygonBatchRenderer {
+    constructor(gl, scope = {}) {
+        Object.defineProperty(this, "gl", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** The terrain state of the draw instance */
+        Object.defineProperty(this, "terrain", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Triangulation results of the draw instance, keyed by feature id */
+        Object.defineProperty(this, "earcutCache", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "program", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "variantName", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: ''
+        });
+        // Projection uniform management
+        Object.defineProperty(this, "projectionUniformManager", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        // Stores the offset uniforms
+        Object.defineProperty(this, "offsetUniforms", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        // Buffers for the batch
+        Object.defineProperty(this, "vertexBuffer", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "indexBuffer", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "vao", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        this.gl = gl;
+        this.terrain = scope.terrain ?? new TerrainContext();
+        this.earcutCache = scope.earcut ?? new EarcutCache();
+        this.projectionUniformManager = new ProjectionUniformManager(gl, {
+            surface: true,
+            terrain: this.terrain,
+        });
+        this.vertexBuffer = gl.createBuffer();
+        this.indexBuffer = gl.createBuffer();
+        this.vao = gl.createVertexArray();
+    }
+    /**
+     * Ensures the shader (recreating it when necessary)
+     */
+    ensureShader(shaderData) {
+        if (this.variantName !== shaderData.variantName) {
+            if (this.program) {
+                this.gl.deleteProgram(this.program);
+            }
+            this.program = this.createShaderProgram(shaderData.vertexShaderPrelude, shaderData.define);
+            this.variantName = shaderData.variantName;
+            // Get the projection uniform locations
+            this.projectionUniformManager.getLocations(this.program);
+            // Set up the VAO
+            this.setupVAO();
+        }
+    }
+    /**
+     * Sets the uniforms for offset mode
+     */
+    setOffsetUniforms(uniforms) {
+        this.offsetUniforms = uniforms;
+    }
+    /**
+     * Creates the shader program (supporting per-vertex color, offset mode)
+     */
+    createShaderProgram(prelude, define) {
+        const projTransitionUniform = getProjectionTransitionUniform(prelude);
+        const vertexSource = `#version 300 es
+${prelude}
+${define}
+${projTransitionUniform}${OFFSET_MODE_GLSL}${TERRAIN_SHADE_VERTEX_GLSL}
+layout(location = 0) in vec2 a_pos;      // relative coords (64-bit precision on the CPU)
+layout(location = 1) in vec4 a_color;    // per-vertex color
+
+out vec4 v_color;
+
+void main() {
+    // High precision version: uses relative coords computed at 64-bit precision on the CPU
+    gl_Position = project_position_to_clipspace_from_offset(a_pos, u_projection_matrix);
+    v_color = a_color;
+    emitShadeOffset(a_pos);
+}`;
+        // The fill gets the same terrain shading as the ground (factor 1.0 when there is no terrain)
+        const fragmentSource = `#version 300 es
+precision highp float;
+
+in vec4 v_color;
+out vec4 fragColor;
+${TERRAIN_SHADE_FRAGMENT_GLSL}
+void main() {
+    fragColor = vec4(v_color.rgb * terrainFillShade(), v_color.a);
+}`;
+        return createProgram(this.gl, vertexSource, fragmentSource);
+    }
+    /**
+     * Sets up the VAO
+     */
+    setupVAO() {
+        const gl = this.gl;
+        gl.bindVertexArray(this.vao);
+        gl.bindBuffer(gl.ARRAY_BUFFER, this.vertexBuffer);
+        // stride: pos(2) + color(4) = 6 floats = 24 bytes
+        const stride = 24;
+        // a_pos: location 0
+        gl.enableVertexAttribArray(0);
+        gl.vertexAttribPointer(0, 2, gl.FLOAT, false, stride, 0);
+        // a_color: location 1
+        gl.enableVertexAttribArray(1);
+        gl.vertexAttribPointer(1, 4, gl.FLOAT, false, stride, 8);
+        // The ELEMENT_ARRAY_BUFFER binding is part of the VAO state
+        gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, this.indexBuffer);
+        gl.bindVertexArray(null);
+    }
+    /**
+     * Sets the projection uniforms (supporting offset mode + globe mode)
+     * @param projectionData MapLibre's ProjectionData
+     * @param zoom The current zoom level (used for switching offset mode)
+     */
+    setProjectionUniforms(projectionData, zoom) {
+        this.projectionUniformManager.setUniforms(projectionData, zoom, this.offsetUniforms);
+    }
+    /**
+     * Batch-draws multiple polygon fills
+     *
+     * @param polygons The array of polygon data (in draw order)
+     * @param projectionData MapLibre's ProjectionData
+     * @param zoom The current zoom level
+     * @returns The number of indices drawn (for debugging)
+     */
+    drawBatch(polygons, projectionData, zoom) {
+        if (!this.program || polygons.length === 0)
+            return 0;
+        const gl = this.gl;
+        // Compute relative coordinates on the CPU side (offset mode: computed at 64-bit precision)
+        const centerLngLat = this.offsetUniforms?.centerLngLat ?? [0, 0];
+        const { vertexData, indexData } = this.buildGeometry(polygons, centerLngLat);
+        if (indexData.length === 0)
+            return 0;
+        // Transfer the vertex data
+        gl.bindBuffer(gl.ARRAY_BUFFER, this.vertexBuffer);
+        gl.bufferData(gl.ARRAY_BUFFER, vertexData, gl.DYNAMIC_DRAW);
+        // Draw
+        gl.useProgram(this.program);
+        this.setProjectionUniforms(projectionData, zoom);
+        gl.bindVertexArray(this.vao);
+        // The ELEMENT_ARRAY_BUFFER binding is VAO state, so the transfer is done after
+        // binding the VAO
+        gl.bufferData(gl.ELEMENT_ARRAY_BUFFER, indexData, gl.DYNAMIC_DRAW);
+        drawFillWithTerrainCull(gl, this.terrain, () => {
+            gl.drawElements(gl.TRIANGLES, indexData.length, gl.UNSIGNED_INT, 0);
+        });
+        gl.bindVertexArray(null);
+        return indexData.length;
+    }
+    /**
+     * Builds the vertex array and index array of the batch
+     *
+     * The indices are laid out in the order of the input polygons, so the draw order
+     * (z-order) is preserved.
+     */
+    buildGeometry(polygons, centerLngLat) {
+        // Pass 1: collect the triangulation results and count the required array lengths
+        const records = [];
+        let totalPoints = 0;
+        let totalIndices = 0;
+        // Subdivide on a grid only while terrain is active or the globe is drawn (on a flat map
+        // without terrain it passes through as null)
+        // The step is decided from the total across all features (the same criterion as
+        // sdf-polygon)
+        const terrainStep = getSurfaceTessellationStep(this.terrain, 'fill');
+        let batchFactor = 1;
+        if (terrainStep) {
+            let totalCells = 0;
+            for (const polygon of polygons) {
+                const outer = polygon.coordinates[0];
+                if (outer)
+                    totalCells += ringBoundingCells(outer, terrainStep.grid, terrainStep.region);
+            }
+            batchFactor = batchTessellationFactor(totalCells);
+            reportTerrainCoarsening(this.terrain, batchFactor);
+        }
+        for (const polygon of polygons) {
+            // Flatten all rings to build the earcut input (inner rings are treated as holes)
+            const { flatCoords, holeIndices, rings } = buildEarcutInput(polygon.coordinates);
+            if (rings.length === 0)
+                continue;
+            // Triangulate with earcut (making use of the cache)
+            let indices;
+            if (polygon.featureId) {
+                // Try to get it from the cache
+                const partIndex = polygon.partIndex ?? 0;
+                const cached = this.earcutCache.get(polygon.featureId, partIndex);
+                if (cached) {
+                    indices = cached;
+                }
+                else {
+                    indices = earcut(flatCoords, holeIndices);
+                    this.earcutCache.set(polygon.featureId, indices, partIndex);
+                }
+            }
+            else {
+                // When there is no featureId, run it without the cache
+                indices = earcut(flatCoords, holeIndices);
+            }
+            if (indices.length === 0)
+                continue;
+            const tessellated = terrainStep
+                ? tessellateSurfaceFill(this.terrain, polygon.featureId, polygon.partIndex ?? 0, flatCoords, indices, {
+                    // While aligned to the actual tile mesh, do not move the step and pass only
+                    // the coarsening factor (so it keeps riding on a subset of the mesh nodes)
+                    grid: terrainStep.tiling ? terrainStep.grid : terrainStep.grid * batchFactor,
+                    maxPoints: terrainStep.maxPoints,
+                    region: terrainStep.region,
+                    tiling: terrainStep.tiling,
+                    coarsen: terrainStep.tiling
+                        ? Math.min(batchFactor, TERRAIN_MAX_TILED_COARSEN)
+                        : undefined,
+                })
+                : { flatCoords, indices };
+            records.push({
+                flatCoords: tessellated.flatCoords,
+                indices: tessellated.indices,
+                color: polygon.color,
+            });
+            totalPoints += tessellated.flatCoords.length / 2;
+            totalIndices += tessellated.indices.length;
+        }
+        // Pass 2: write directly into the typed arrays
+        const vertexData = new Float32Array(totalPoints * 6);
+        const indexData = new Uint32Array(totalIndices);
+        let base = 0;
+        let indexOffset = 0;
+        for (const { flatCoords, indices, color } of records) {
+            const pointCount = flatCoords.length / 2;
+            for (let i = 0; i < pointCount; i++) {
+                // Compute the offset from the center at 64-bit precision
+                const offset = calculateLngLatOffset([flatCoords[i * 2], flatCoords[i * 2 + 1]], centerLngLat);
+                const at = (base + i) * 6;
+                vertexData[at] = offset[0];
+                vertexData[at + 1] = offset[1];
+                vertexData[at + 2] = color[0];
+                vertexData[at + 3] = color[1];
+                vertexData[at + 4] = color[2];
+                vertexData[at + 5] = color[3];
+            }
+            for (let i = 0; i < indices.length; i++) {
+                indexData[indexOffset + i] = indices[i] + base;
+            }
+            base += pointCount;
+            indexOffset += indices.length;
+        }
+        return { vertexData, indexData };
+    }
+    /**
+     * Disposes of the resources
+     */
+    dispose() {
+        const gl = this.gl;
+        if (this.program) {
+            gl.deleteProgram(this.program);
+            this.program = null;
+        }
+        if (this.vertexBuffer) {
+            gl.deleteBuffer(this.vertexBuffer);
+            this.vertexBuffer = null;
+        }
+        if (this.indexBuffer) {
+            gl.deleteBuffer(this.indexBuffer);
+            this.indexBuffer = null;
+        }
+        if (this.vao) {
+            gl.deleteVertexArray(this.vao);
+            this.vao = null;
+        }
+    }
+}

package/dist/view/renderers/polygon/earcut-input.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Building the earcut input
+ *
+ * Provides a pure function that converts a polygon with holes (an array of rings)
+ * into the "flattened coordinate sequence + start indices of the inner rings" that
+ * earcut requires. Following the coordinate format convention, rings[0] is the outer
+ * ring and rings[1..] are the inner rings.
+ */
+import type { Coordinate } from '../../../store/types.js';
+/**
+ * The input to earcut
+ */
+export interface EarcutInput {
+    /** Coordinate sequence flattened over all rings ([lng, lat, lng, lat, ...]) */
+    flatCoords: number[];
+    /** Start vertex indices of the inner rings (earcut's holeIndices) */
+    holeIndices: number[];
+    /**
+     * Array of rings with the closing point removed (rings[0] is the outer ring,
+     * rings[1..] are the inner rings)
+     *
+     * Rings that have no area have already been excluded, so it can also be used for
+     * drawing the outline (stroke).
+     */
+    rings: Coordinate[][];
+}
+/**
+ * Builds the earcut input from an array of rings
+ *
+ * - The closing point of each ring is removed
+ * - A ring with fewer than 3 vertices has no area, so it is ignored
+ * - If the outer ring is invalid, an empty input is returned (the caller skips drawing)
+ *
+ * @param rings Array of rings (rings[0] is the outer ring, rings[1..] are the inner rings)
+ * @returns The flattened coordinate sequence and the start indices of the inner rings
+ */
+export declare function buildEarcutInput(rings: Coordinate[][]): EarcutInput;

package/dist/view/renderers/polygon/earcut-input.js

@@ -0,0 +1,55 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Removes the closing point at the end of a ring (the same coordinate as the first)
+ *
+ * Neither earcut nor outline drawing needs the closing point, so it is normalized at
+ * the entrance.
+ */
+function openRing(ring) {
+    if (ring.length < 2)
+        return ring;
+    const first = ring[0];
+    const last = ring[ring.length - 1];
+    if (first[0] === last[0] && first[1] === last[1]) {
+        return ring.slice(0, -1);
+    }
+    return ring;
+}
+/**
+ * Builds the earcut input from an array of rings
+ *
+ * - The closing point of each ring is removed
+ * - A ring with fewer than 3 vertices has no area, so it is ignored
+ * - If the outer ring is invalid, an empty input is returned (the caller skips drawing)
+ *
+ * @param rings Array of rings (rings[0] is the outer ring, rings[1..] are the inner rings)
+ * @returns The flattened coordinate sequence and the start indices of the inner rings
+ */
+export function buildEarcutInput(rings) {
+    if (rings.length === 0) {
+        return { flatCoords: [], holeIndices: [], rings: [] };
+    }
+    const outerRing = openRing(rings[0]);
+    if (outerRing.length < 3) {
+        return { flatCoords: [], holeIndices: [], rings: [] };
+    }
+    const flatCoords = [];
+    const holeIndices = [];
+    const openRings = [outerRing];
+    for (const [lng, lat] of outerRing) {
+        flatCoords.push(lng, lat);
+    }
+    for (let i = 1; i < rings.length; i++) {
+        const holeRing = openRing(rings[i]);
+        if (holeRing.length < 3)
+            continue;
+        // Start vertex index of the inner ring (coordinate count = flatCoords.length / 2)
+        holeIndices.push(flatCoords.length / 2);
+        for (const [lng, lat] of holeRing) {
+            flatCoords.push(lng, lat);
+        }
+        openRings.push(holeRing);
+    }
+    return { flatCoords, holeIndices, rings: openRings };
+}

package/dist/view/renderers/polygon/earcut-sliced.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The number of ear clipping loop iterations run in a single step
+ *
+ * The caller checks the clock at this granularity, so this determines "how far the
+ * budget can be overrun". The measurements on a million-vertex water body are as
+ * follows.
+ *
+ * | slice | average per step | p99 | max | total CPU of the triangulation |
+ * | --- | --- | --- | --- | --- |
+ * | 16 | 0.14ms | 5.1ms | 23ms | 15.0s |
+ * | 32 | 0.28ms | 10.3ms | 35ms | 15.3s |
+ * | 64 | 0.52ms | 19.5ms | 55ms | 14.2s |
+ *
+ * Since the total hardly changes even when the slice is made finer (the cost of slicing
+ * is negligible), 16 is adopted because it keeps within the budget. A long step appears
+ * rarely because the recovery performed when no more ears can be found (the full sweep
+ * of filterPoints) runs within a single iteration.
+ */
+export declare const EARCUT_SLICE_ITERATIONS = 16;
+/**
+ * Time-sliceable earcut
+ *
+ * If `step()` is called repeatedly until completion (true), `triangles` ends up holding
+ * the same index sequence as the `earcut(data, holeIndices, dim)` dependency.
+ */
+export declare class SlicedEarcut {
+    private readonly data;
+    private readonly holeIndices;
+    private readonly dim;
+    /** The triangulation result (partial progress until it finishes) */
+    readonly triangles: number[];
+    private phase;
+    private ear;
+    private stop;
+    private cured;
+    private minX;
+    private minY;
+    private invSize;
+    /** The steiner points of this job (swapped into the module variable at step's entrance) */
+    private readonly ownSteiners;
+    /** The filteredOut of this job (same as above) */
+    private ownFilteredOut;
+    constructor(data: ArrayLike<number>, holeIndices?: ArrayLike<number> | null, dim?: number);
+    /** Whether it has finished */
+    get done(): boolean;
+    /**
+     * Advances the triangulation a little
+     *
+     * @param iterations The upper bound on ear clipping loop iterations (the default slice
+     *   when omitted)
+     * @returns true once it has finished
+     */
+    step(iterations?: number): boolean;
+    /**
+     * Preprocessing (building the linked list, bridging the holes, bbox, z-order indexing)
+     *
+     * This part is not sliced. It takes only tens of milliseconds even at a million
+     * vertices, so fidelity to the port is preferred over the value of slicing it.
+     */
+    private runSetup;
+    /**
+     * The main ear clipping loop (identical to upstream's earcutLinked; breaks out on the
+     * iteration count)
+     *
+     * splitEarcut, the last resort, is recursive, so it is not sliced (it is a path that
+     * runs only once against the remaining polygon and is not taken for ordinary inputs).
+     */
+    private runClip;
+}