@sakuzu/maplibre-gl-draw 1.0.0

package/dist/view/renderers/draw-factors.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Draw factors for retained-mode rendering (size and opacity)
+ *
+ * A retained batch bakes its vertex data, so changing dimensions or colors
+ * would normally require rebuilding it. Per-frame adjustments such as "make it
+ * slightly thinner and fainter as the zoom changes" can, however, be done with
+ * a uniform that is multiplied into the baked values at draw time. This module
+ * only defines the shape in which those factors are passed around.
+ *
+ * Conventions:
+ *
+ * - The default is `NEUTRAL_DRAW_FACTORS` (1x scale, opacity 1), so calls that
+ *   pass no factors (Store rendering, immediate mode) look exactly as before,
+ *   down to the pixel
+ * - A uniform is per-program residual state, so even rendering paths that do
+ *   not use the factors must write 1 (a value left over from a previous draw
+ *   makes another draw come out thinner; this is the same family of accident as
+ *   forgetting to restore the blend state)
+ * - The factors are a per-dataset adjustment and do not propagate to the
+ *   Store (the drawn features)
+ */
+/**
+ * Factors multiplied in at draw time
+ */
+export interface RetainedDrawFactors {
+    /**
+     * Size factor (applies to point diameter, line width and outline width). 1 keeps the
+     * former look
+     */
+    scale: number;
+    /** Opacity factor (0..1). 1 keeps the former look */
+    opacity: number;
+}
+/**
+ * No factors (the former look)
+ */
+export declare const NEUTRAL_DRAW_FACTORS: RetainedDrawFactors;
+/**
+ * Round factors that came from outside into a safe range
+ *
+ * This is a defense so that rendering is not broken when a caller's function
+ * returns NaN, infinity or a negative value. Only positive finite numbers are
+ * accepted for scale (anything else becomes 1), and opacity is clamped to
+ * 0..1.
+ */
+export declare function sanitizeDrawFactors(factors: {
+    scale: number;
+    opacity: number;
+} | null | undefined): RetainedDrawFactors;
+/**
+ * The draw-time factors of a Store layer (its opacity)
+ *
+ * `Layer.opacity` is a look-only setting, so it is applied at draw time rather than baked into
+ * the vertex data: a change of the value does not rebuild a retained batch. The size is not
+ * touched (scale 1). A missing layer, and an opacity of 1, give `NEUTRAL_DRAW_FACTORS` itself;
+ * a value outside 0..1 or not finite is rounded the same way as `sanitizeDrawFactors`.
+ */
+export declare function layerDrawFactors(layer: {
+    readonly opacity?: number;
+} | null | undefined): RetainedDrawFactors;

package/dist/view/renderers/draw-factors.js

@@ -0,0 +1,35 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * No factors (the former look)
+ */
+export const NEUTRAL_DRAW_FACTORS = { scale: 1, opacity: 1 };
+/**
+ * Round factors that came from outside into a safe range
+ *
+ * This is a defense so that rendering is not broken when a caller's function
+ * returns NaN, infinity or a negative value. Only positive finite numbers are
+ * accepted for scale (anything else becomes 1), and opacity is clamped to
+ * 0..1.
+ */
+export function sanitizeDrawFactors(factors) {
+    if (!factors)
+        return NEUTRAL_DRAW_FACTORS;
+    const scale = Number.isFinite(factors.scale) && factors.scale > 0 ? factors.scale : 1;
+    const opacity = Number.isFinite(factors.opacity) ? Math.min(1, Math.max(0, factors.opacity)) : 1;
+    return { scale, opacity };
+}
+/**
+ * The draw-time factors of a Store layer (its opacity)
+ *
+ * `Layer.opacity` is a look-only setting, so it is applied at draw time rather than baked into
+ * the vertex data: a change of the value does not rebuild a retained batch. The size is not
+ * touched (scale 1). A missing layer, and an opacity of 1, give `NEUTRAL_DRAW_FACTORS` itself;
+ * a value outside 0..1 or not finite is rounded the same way as `sanitizeDrawFactors`.
+ */
+export function layerDrawFactors(layer) {
+    const opacity = layer?.opacity;
+    if (opacity === undefined || opacity === 1)
+        return NEUTRAL_DRAW_FACTORS;
+    return sanitizeDrawFactors({ scale: 1, opacity });
+}

package/dist/view/renderers/drawer.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/view/renderers/drawer.js

@@ -0,0 +1,346 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { generateCirclePolygon } from '../../shared/math/index.js';
+import { hexToColor } from '../../shared/utils/color.js';
+import { getCircleRadius, getCreatedZoom } from '../../shared/utils/property.js';
+import { StyleRuleCache } from '../cache/style-rule.js';
+import { applyRuleColor } from '../style-rule.js';
+import { layerDrawFactors } from './draw-factors.js';
+import { resolvePointStyle } from './point/point-style.js';
+import { FillShaderManager } from './polygon/fill.js';
+/**
+ * The feature rendering class
+ *
+ * @internal
+ */
+export class FeatureDrawer {
+    constructor(deps) {
+        Object.defineProperty(this, "map", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Evaluated style rules of the draw instance, keyed by feature id */
+        Object.defineProperty(this, "styleRules", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "sdfLineRenderer", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "pointShapeRenderer", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "imageRenderer", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "featureStyle", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "fillShaderManager", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.map = deps.map;
+        this.sdfLineRenderer = deps.sdfLineRenderer;
+        this.pointShapeRenderer = deps.pointShapeRenderer;
+        this.imageRenderer = deps.imageRenderer;
+        this.featureStyle = deps.featureStyle;
+        this.styleRules = deps.styleRules ?? new StyleRuleCache();
+        this.fillShaderManager = new FillShaderManager(deps.gl, deps.terrain);
+    }
+    /**
+     * Make sure the shader exists
+     */
+    ensureShader(shaderData) {
+        this.fillShaderManager.ensureShader(shaderData);
+    }
+    /**
+     * Set the uniforms for offset mode
+     */
+    setOffsetUniforms(uniforms) {
+        this.fillShaderManager.setOffsetUniforms(uniforms);
+    }
+    /**
+     * Draw a feature
+     *
+     * @param layer The layer it belongs to (used to evaluate style rules, and its opacity is
+     *   multiplied into the drawing; no rules and no factor when omitted)
+     */
+    drawFeature(feature, projectionData, zoom, layer) {
+        const opacity = layerDrawFactors(layer).opacity;
+        if (feature.type === 'Point') {
+            const coord = feature.coordinates;
+            const pointStyle = pointWithOpacity(this.getPointStyle(feature, layer), opacity);
+            this.drawPointShape(coord, pointStyle, zoom, feature.id);
+        }
+        else if (feature.type === 'LineString') {
+            const coords = feature.coordinates;
+            const createdZoom = getCreatedZoom(feature) ?? zoom;
+            const strokeStyle = strokeWithOpacity(this.getLineStringStrokeStyle(feature, layer), opacity);
+            this.drawLineStringStroke(coords, strokeStyle, projectionData, zoom, createdZoom, feature.id);
+        }
+        else if (feature.type === 'Polygon') {
+            const rings = feature.coordinates;
+            const createdZoom = getCreatedZoom(feature) ?? zoom;
+            const { fillColor, strokeStyle } = polygonWithOpacity(this.getPolygonStyles(feature, layer), opacity);
+            this.drawPolygonWithStroke(rings, fillColor, strokeStyle, projectionData, zoom, createdZoom, feature.id);
+        }
+        else if (feature.type === 'MultiPoint') {
+            // Draw a point for each part (the style is shared across the feature)
+            const parts = feature.coordinates;
+            const pointStyle = pointWithOpacity(this.getPointStyle(feature, layer), opacity);
+            for (const coord of parts) {
+                this.drawPointShape(coord, pointStyle, zoom, feature.id);
+            }
+        }
+        else if (feature.type === 'MultiLineString') {
+            // Draw a line for each part
+            const parts = feature.coordinates;
+            const createdZoom = getCreatedZoom(feature) ?? zoom;
+            const strokeStyle = strokeWithOpacity(this.getLineStringStrokeStyle(feature, layer), opacity);
+            for (let i = 0; i < parts.length; i++) {
+                this.drawLineStringStroke(parts[i], strokeStyle, projectionData, zoom, createdZoom, `${feature.id}:part:${i}`);
+            }
+        }
+        else if (feature.type === 'MultiPolygon') {
+            // Draw a hole-aware polygon for each part
+            const parts = feature.coordinates;
+            const createdZoom = getCreatedZoom(feature) ?? zoom;
+            const { fillColor, strokeStyle } = polygonWithOpacity(this.getPolygonStyles(feature, layer), opacity);
+            for (let i = 0; i < parts.length; i++) {
+                this.drawPolygonWithStroke(parts[i], fillColor, strokeStyle, projectionData, zoom, createdZoom, `${feature.id}:part:${i}`);
+            }
+        }
+        else if (feature.type === 'Image') {
+            this.imageRenderer.draw(feature, projectionData, zoom, () => this.map.triggerRepaint(), opacity);
+        }
+        else if (feature.type === 'Circle') {
+            this.drawCircle(feature, projectionData, zoom, layer, opacity);
+        }
+        else if (feature.type === 'Freehand') {
+            // Freehand uses the same rendering logic as LineString
+            const coords = feature.coordinates;
+            const createdZoom = getCreatedZoom(feature) ?? zoom;
+            const strokeStyle = strokeWithOpacity(this.getLineStringStrokeStyle(feature, layer), opacity);
+            this.drawLineStringStroke(coords, strokeStyle, projectionData, zoom, createdZoom, feature.id);
+        }
+    }
+    /**
+     * Resolve the effective style
+     *
+     * The precedence is "per-feature color > the layer's style rule > the default color".
+     * The result of evaluating the rules is cached by feature ID and invalidated when the
+     * feature is updated and when the layer rules change (done by CustomLayer, which
+     * subscribes to the Store).
+     */
+    resolveStyle(feature, layer, channel) {
+        if (!feature)
+            return undefined;
+        const style = feature.style;
+        const ruleColor = this.styleRules.resolve(feature, layer?.styleRule);
+        return applyRuleColor(style, ruleColor, channel);
+    }
+    /**
+     * Get the style of a Point (merges feature.style, the layer rules and the defaults)
+     *
+     * Every built-in path reads the style of a point here (instanced and immediate drawing, the
+     * classification of the retained runs, the datasets), so the shape a feature
+     * names (`pointShape`) wins over the default of the instance on all of them.
+     *
+     * @param feature The target feature
+     * @param layer The layer it belongs to (used to evaluate style rules; no rules when omitted)
+     */
+    getPointStyle(feature, layer) {
+        return resolvePointStyle(this.resolveStyle(feature, layer, 'point'), this.featureStyle.point.point);
+    }
+    /**
+     * Get the stroke style of a LineString
+     *
+     * @param feature The target feature
+     * @param layer The layer it belongs to (used to evaluate style rules; no rules when omitted)
+     */
+    getLineStringStrokeStyle(feature, layer) {
+        const defaultStyle = this.featureStyle.lineString.stroke;
+        const style = this.resolveStyle(feature, layer, 'stroke');
+        if (!style)
+            return defaultStyle;
+        // Apply strokeOpacity when it is specified, even if strokeColor is not set
+        // strokeOpacity is set directly rather than multiplied into the default alpha value
+        const color = style.strokeColor
+            ? hexToColor(style.strokeColor, style.strokeOpacity ?? 1)
+            : style.strokeOpacity !== undefined
+                ? [defaultStyle.color[0], defaultStyle.color[1], defaultStyle.color[2], style.strokeOpacity]
+                : defaultStyle.color;
+        return {
+            ...defaultStyle,
+            color,
+            width: style.strokeWidth ?? defaultStyle.width,
+            // The opacity is already folded into color, so opacity is set to 1
+            opacity: 1,
+            lineStyle: style.lineStyle ?? defaultStyle.lineStyle,
+        };
+    }
+    /**
+     * Get the style of a Polygon (fill + stroke)
+     *
+     * The color from a style rule is applied to the fill (fillColor). The outline is
+     * determined by the per-feature style and the default color.
+     *
+     * @param feature The target feature
+     * @param layer The layer it belongs to (used to evaluate style rules; no rules when omitted)
+     */
+    getPolygonStyles(feature, layer) {
+        const defaultFillColor = this.featureStyle.polygon.fill.color;
+        const defaultStrokeStyle = this.featureStyle.polygon.stroke;
+        const style = this.resolveStyle(feature, layer, 'fill');
+        if (!style) {
+            return { fillColor: defaultFillColor, strokeStyle: defaultStrokeStyle };
+        }
+        // Apply fillOpacity when it is specified, even if fillColor is not set
+        // fillOpacity is set directly rather than multiplied into the default alpha value
+        // When fillOpacity is not set, the default polygon fill alpha (from the config) is used.
+        // So that a feature with only fillColor specified does not become opaque (alpha 1),
+        // it follows the alpha component of the default color rather than a hardcoded 1.
+        const fillColor = style.fillColor
+            ? hexToColor(style.fillColor, style.fillOpacity ?? defaultFillColor[3])
+            : style.fillOpacity !== undefined
+                ? [defaultFillColor[0], defaultFillColor[1], defaultFillColor[2], style.fillOpacity]
+                : defaultFillColor;
+        // Apply strokeOpacity when it is specified, even if strokeColor is not set
+        // strokeOpacity is set directly rather than multiplied into the default alpha value
+        const strokeColor = style.strokeColor
+            ? hexToColor(style.strokeColor, style.strokeOpacity ?? 1)
+            : style.strokeOpacity !== undefined
+                ? [
+                    defaultStrokeStyle.color[0],
+                    defaultStrokeStyle.color[1],
+                    defaultStrokeStyle.color[2],
+                    style.strokeOpacity,
+                ]
+                : defaultStrokeStyle.color;
+        const strokeStyle = {
+            ...defaultStrokeStyle,
+            color: strokeColor,
+            width: style.strokeWidth ?? defaultStrokeStyle.width,
+            // The opacity is already folded into color, so opacity is set to 1
+            opacity: 1,
+            lineStyle: style.lineStyle ?? defaultStrokeStyle.lineStyle,
+        };
+        return { fillColor, strokeStyle };
+    }
+    /**
+     * Draw a Point shape
+     */
+    drawPointShape(coord, style, zoom, featureId) {
+        this.pointShapeRenderer.draw(coord, style, zoom, featureId);
+    }
+    /**
+     * Draw the stroke of a LineString (computed on the GPU)
+     */
+    drawLineStringStroke(coords, style, projectionData, zoom, createdZoom, featureId) {
+        if (coords.length < 2)
+            return;
+        // Compute widthPixels = style.width * 2^(zoom - createdZoom) on the GPU
+        this.sdfLineRenderer.draw(coords, style, { widthUnit: 'pixels', closed: false, featureId, createdZoom }, zoom, projectionData);
+    }
+    /**
+     * Draw a Polygon with a fill and a stroke
+     */
+    drawPolygonWithStroke(rings, fillColor, strokeStyle, projectionData, zoom, createdZoom, featureId) {
+        if (rings.length === 0)
+            return;
+        const outerRing = rings[0];
+        if (outerRing.length < 3)
+            return;
+        // Fill (inner rings are punched out as holes)
+        if (fillColor[3] > 0) {
+            this.fillShaderManager.drawPolygonRings(rings, fillColor, projectionData, zoom);
+        }
+        // Stroke (computed on the GPU): the outer ring and each inner ring are drawn as closed paths
+        if (strokeStyle.opacity > 0) {
+            for (let i = 0; i < rings.length; i++) {
+                const ring = rings[i];
+                if (ring.length < 3)
+                    continue;
+                this.sdfLineRenderer.drawClosed(ring, strokeStyle, {
+                    widthUnit: 'pixels',
+                    featureId: featureId ? `${featureId}:stroke:${i}` : undefined,
+                    createdZoom,
+                }, zoom, projectionData);
+            }
+        }
+    }
+    /**
+     * Draw a Circle
+     */
+    drawCircle(feature, projectionData, zoom, layer, opacity = 1) {
+        const center = feature.coordinates;
+        const radiusMeters = getCircleRadius(feature);
+        if (!radiusMeters || radiusMeters <= 0)
+            return;
+        const createdZoom = getCreatedZoom(feature) ?? zoom;
+        const { fillColor, strokeStyle } = polygonWithOpacity(this.getPolygonStyles(feature, layer), opacity);
+        // Convert the circle into a polygon
+        const circleCoords = generateCirclePolygon(center, radiusMeters);
+        // Fill
+        if (fillColor[3] > 0) {
+            this.fillShaderManager.drawPolygon(circleCoords, fillColor, projectionData, zoom);
+        }
+        // Stroke
+        if (strokeStyle.opacity > 0) {
+            this.sdfLineRenderer.drawClosed(circleCoords, strokeStyle, {
+                widthUnit: 'pixels',
+                featureId: feature.id ? `${feature.id}:stroke` : undefined,
+                createdZoom,
+            }, zoom, projectionData);
+        }
+    }
+    /**
+     * Release the resources
+     */
+    dispose() {
+        this.fillShaderManager.dispose();
+    }
+}
+/** A point style with an opacity factor multiplied in (the same object at 1) */
+function pointWithOpacity(style, opacity) {
+    if (opacity === 1)
+        return style;
+    return {
+        ...style,
+        fillOpacity: style.fillOpacity * opacity,
+        strokeOpacity: style.strokeOpacity * opacity,
+    };
+}
+/** A stroke style with an opacity factor multiplied in (the same object at 1) */
+function strokeWithOpacity(style, opacity) {
+    return opacity === 1 ? style : { ...style, opacity: style.opacity * opacity };
+}
+/** Polygon styles with an opacity factor multiplied into the fill and the outline */
+function polygonWithOpacity(styles, opacity) {
+    if (opacity === 1)
+        return styles;
+    const { fillColor, strokeStyle } = styles;
+    return {
+        fillColor: [fillColor[0], fillColor[1], fillColor[2], fillColor[3] * opacity],
+        strokeStyle: strokeWithOpacity(strokeStyle, opacity),
+    };
+}

package/dist/view/renderers/image.d.ts

@@ -0,0 +1 @@
+export {};