@sakuzu/maplibre-gl-draw 1.0.0

package/dist/view/renderers/image.js

@@ -0,0 +1,255 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { getMetersPerPixel, metersToDegreesLat, metersToDegreesLng, } from '../../shared/math/index.js';
+import { getTileSize } from '../../shared/utils/map.js';
+import { getImageProperties } from '../../shared/utils/property.js';
+import { computeQuadVertices } from '../shaders/quad.js';
+/**
+ * The default image style
+ * width/height: 0 = use the original size
+ */
+const DEFAULT_IMAGE_STYLE = {
+    width: 0,
+    height: 0,
+    rotation: 0,
+    opacity: 1.0,
+    imageOpacity: 1,
+};
+/**
+ * ImageRenderer
+ *
+ * @internal
+ */
+export class ImageRenderer {
+    constructor(map, _gl, textureCache, quadShader, getFileData, onError) {
+        Object.defineProperty(this, "map", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "textureCache", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "quadShader", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "getFileData", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "onError", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Features drawn while their image was decoding, by dataURL (reported if it fails) */
+        Object.defineProperty(this, "waitingFeatures", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        /** The dataURL each feature was last reported for, by feature ID */
+        Object.defineProperty(this, "reportedFailures", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        this.map = map;
+        this.textureCache = textureCache;
+        this.quadShader = quadShader;
+        this.getFileData = getFileData;
+        this.onError = onError;
+    }
+    /**
+     * Get the tile size
+     */
+    getMapTileSize() {
+        return getTileSize(this.map);
+    }
+    /**
+     * Draw an image feature
+     *
+     * @param feature The image feature
+     * @param projectionData MapLibre's ProjectionData
+     * @param zoom The current zoom level
+     * @param onNeedRedraw Callback for when a redraw is needed
+     * @param opacityFactor Multiplied into the opacity of the image (the opacity of its layer)
+     */
+    draw(feature, projectionData, zoom, onNeedRedraw, opacityFactor = 1) {
+        if (feature.type !== 'Image')
+            return;
+        const properties = getImageProperties(feature);
+        if (!properties.imageFileId)
+            return;
+        // Obtain the FileData from the Store
+        const fileData = this.getFileData(properties.imageFileId);
+        // No FileData yet: a transient state (in a shared document the feature can arrive before
+        // its file), so the feature is drawn without its image and nothing is logged.
+        if (!fileData)
+            return;
+        const coord = feature.coordinates;
+        const latitude = coord[1];
+        const style = this.getImageStyle(feature.style);
+        // The texture is keyed by the dataURL. While the image is decoding nothing is drawn; the
+        // decode (shared per dataURL) requests a redraw when it finishes, and that frame uploads it
+        const imageFileId = properties.imageFileId;
+        const src = fileData.dataURL;
+        const textureInfo = this.textureCache.acquireImageTexture(src, () => {
+            this.waitingFeatures.delete(src);
+            onNeedRedraw?.();
+        }, (error) => {
+            console.error(`Failed to load image: ${imageFileId}`, error);
+            this.reportFailure(src, error);
+        });
+        if (!textureInfo) {
+            this.noteMissingImage(feature.id, src);
+            return;
+        }
+        // Determine the size (use the size stored in ImageProperties)
+        const imageWidth = properties.imageWidth || textureInfo.width;
+        const imageHeight = properties.imageHeight || textureInfo.height;
+        // Use the size specified by the style, or the original size
+        const displayWidth = style.width || imageWidth;
+        const displayHeight = style.height || imageHeight;
+        // Scale relative to how it is displayed at createdZoom
+        // At createdZoom the image is displayed at its original pixel size
+        const createdZoom = properties.createdZoom || zoom;
+        const scale = properties.scale || 1;
+        // Pixel -> meter conversion at createdZoom
+        const tileSize = this.getMapTileSize();
+        const metersPerPixel = getMetersPerPixel(latitude, createdZoom, tileSize);
+        const widthMeters = displayWidth * scale * metersPerPixel;
+        const heightMeters = displayHeight * scale * metersPerPixel;
+        // Convert meters -> degrees
+        const widthDeg = metersToDegreesLng(widthMeters, latitude);
+        const heightDeg = metersToDegreesLat(heightMeters);
+        // Rotation angle (degrees -> radians)
+        const rotationRad = (((style.rotation || 0) + (properties.rotation || 0)) * Math.PI) / 180;
+        // Compute the quad vertices
+        const vertices = computeQuadVertices(coord[0], coord[1], widthDeg, heightDeg, rotationRad);
+        // Draw (imageOpacity takes precedence; otherwise opacity is used)
+        const opacity = (style.imageOpacity ?? style.opacity ?? 1.0) * opacityFactor;
+        this.quadShader.draw(vertices, textureInfo.texture, opacity, projectionData, zoom);
+    }
+    /**
+     * Merge the image style
+     */
+    /**
+     * Records a feature whose image is not drawn: reports it at once when the image has failed,
+     * otherwise waits for the decode (the cache tells only the caller that started it)
+     */
+    noteMissingImage(featureId, src) {
+        const error = this.textureCache.getImageError(src);
+        if (error) {
+            this.reportFeature(featureId, src, error);
+            return;
+        }
+        let waiting = this.waitingFeatures.get(src);
+        if (!waiting) {
+            waiting = new Set();
+            this.waitingFeatures.set(src, waiting);
+        }
+        waiting.add(featureId);
+    }
+    /** Reports every feature that was waiting for an image that failed */
+    reportFailure(src, error) {
+        const waiting = this.waitingFeatures.get(src);
+        this.waitingFeatures.delete(src);
+        for (const featureId of waiting ?? [])
+            this.reportFeature(featureId, src, error);
+    }
+    /** Reports a feature once per image */
+    reportFeature(featureId, src, error) {
+        if (this.reportedFailures.get(featureId) === src)
+            return;
+        this.reportedFailures.set(featureId, src);
+        this.onError?.(featureId, error);
+    }
+    getImageStyle(style) {
+        return {
+            ...DEFAULT_IMAGE_STYLE,
+            ...style,
+        };
+    }
+    /**
+     * Compute the bounding box of an image (in degrees)
+     *
+     * @param feature The image feature
+     * @param zoom The current zoom level
+     * @returns The bounding box { minX, minY, maxX, maxY }
+     */
+    computeBounds(feature, zoom) {
+        if (feature.type !== 'Image')
+            return null;
+        const properties = getImageProperties(feature);
+        if (!properties.imageFileId)
+            return null;
+        const coord = feature.coordinates;
+        const latitude = coord[1];
+        const style = this.getImageStyle(feature.style);
+        // Determine the size
+        const imageWidth = properties.imageWidth || style.width;
+        const imageHeight = properties.imageHeight || style.height;
+        const displayWidth = style.width || imageWidth;
+        const displayHeight = style.height || imageHeight;
+        // Scale relative to how it is displayed at createdZoom
+        const createdZoom = properties.createdZoom || zoom;
+        const scale = properties.scale || 1;
+        // Pixel -> meter conversion at createdZoom
+        const tileSize = this.getMapTileSize();
+        const metersPerPixel = getMetersPerPixel(latitude, createdZoom, tileSize);
+        const widthMeters = displayWidth * scale * metersPerPixel;
+        const heightMeters = displayHeight * scale * metersPerPixel;
+        // Convert meters -> degrees
+        const widthDeg = metersToDegreesLng(widthMeters, latitude);
+        const heightDeg = metersToDegreesLat(heightMeters);
+        // Rotation angle
+        const rotationRad = (((style.rotation || 0) + (properties.rotation || 0)) * Math.PI) / 180;
+        // Compute the quad vertices
+        const vertices = computeQuadVertices(coord[0], coord[1], widthDeg, heightDeg, rotationRad);
+        // Compute the bounding box
+        const lngs = [
+            this.mercatorToLng(vertices.topLeft[0]),
+            this.mercatorToLng(vertices.topRight[0]),
+            this.mercatorToLng(vertices.bottomLeft[0]),
+            this.mercatorToLng(vertices.bottomRight[0]),
+        ];
+        const lats = [
+            this.mercatorToLat(vertices.topLeft[1]),
+            this.mercatorToLat(vertices.topRight[1]),
+            this.mercatorToLat(vertices.bottomLeft[1]),
+            this.mercatorToLat(vertices.bottomRight[1]),
+        ];
+        return {
+            minX: Math.min(...lngs),
+            minY: Math.min(...lats),
+            maxX: Math.max(...lngs),
+            maxY: Math.max(...lats),
+        };
+    }
+    /**
+     * Convert a Mercator X coordinate to longitude
+     */
+    mercatorToLng(x) {
+        return x * 360 - 180;
+    }
+    /**
+     * Convert a Mercator Y coordinate to latitude
+     */
+    mercatorToLat(y) {
+        const n = Math.PI - 2 * Math.PI * y;
+        return (180 / Math.PI) * Math.atan(0.5 * (Math.exp(n) - Math.exp(-n)));
+    }
+}

package/dist/view/renderers/line/dash.d.ts

@@ -0,0 +1,31 @@
+import type { Coordinate } from '../../../shared/types/model.js';
+export type { Coordinate };
+/** One dash of a dashed line, as returned by {@link splitIntoDashes}. */
+export interface DashSegment {
+    /** The positions `[lng, lat]` of the dash, at least 2 */
+    coords: Coordinate[];
+}
+/**
+ * Splits a line into the pieces of a dash pattern measured in screen pixels at a zoom.
+ *
+ * Lengths are measured in Web Mercator pixels of 512 px tiles, so the dashes look the
+ * specified length on screen at `zoom`. The pattern continues across vertices.
+ *
+ * @param coords The vertices `[lng, lat]` in degrees
+ * @param dashLength The dash length in screen px
+ * @param gapLength The gap length in screen px
+ * @param zoom The zoom the lengths are measured at
+ * @returns The dashes, in order along the line. An empty array for fewer than 2 positions
+ */
+export declare function splitIntoDashes(coords: Coordinate[], dashLength: number, gapLength: number, zoom: number): DashSegment[];
+/**
+ * Returns the dash and gap lengths in px that suit a line style at a line width.
+ *
+ * Unlike getDashPattern (preset) in shared/math, this computes dynamically from the stroke
+ * width.
+ *
+ * @param lineStyle The line style
+ * @param strokeWidth The line thickness at draw time (pixels)
+ * @returns [dashLength, gapLength], or null (for a solid line)
+ */
+export declare function getStrokeDashPattern(lineStyle: 'solid' | 'dashed' | 'dotted', strokeWidth?: number): [number, number] | null;

package/dist/view/renderers/line/dash.js

@@ -0,0 +1,152 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Dash pattern computation utilities
+ *
+ * Precomputes the dash pattern on the CPU side and returns each dash as an individual segment
+ */
+import { DEFAULT_TILE_SIZE } from '../../../shared/math/index.js';
+const RADIANS_PER_DEGREE = Math.PI / 180;
+/**
+ * Measures the distance between two points in screen pixels
+ *
+ * The dash length and gap length arrive in screen pixels (the caller derives them from the
+ * effective line width), so unless the path is measured on exactly the same scale, the result
+ * will not look the way it was specified.
+ *
+ * In Web Mercator:
+ *   - 1 degree of longitude = worldSize / 360 px (constant regardless of latitude)
+ *   - 1 degree of latitude = 1 / cos(lat) times that (stretched more at higher latitudes)
+ * where worldSize = tileSize x 2^zoom (tileSize is 512).
+ *
+ * The old implementation used 156543 m/px (= the zoom 0 resolution based on 256 px tiles) and
+ * did not account for the latitude stretch either, so it estimated the path length at 1/2 to
+ * 1/2.5 of its actual size. As a result, dashes were drawn 2 to 2.5 times longer than
+ * specified, and short paths fit within a single dash and looked solid.
+ */
+function calculateDistance(p1, p2, zoom, tileSize = DEFAULT_TILE_SIZE) {
+    const pixelsPerLngDegree = (tileSize * 2 ** zoom) / 360;
+    // Determine the stretch per degree from the latitude at the middle of the interval (the
+    // mapping is affine within the interval, so interpolating with the ratio computed here still
+    // gives exactly the same intersection positions)
+    const latitude = (p1[1] + p2[1]) / 2;
+    const cosLatitude = Math.max(Math.cos(latitude * RADIANS_PER_DEGREE), 1e-6);
+    const x = (p2[0] - p1[0]) * pixelsPerLngDegree;
+    const y = ((p2[1] - p1[1]) * pixelsPerLngDegree) / cosLatitude;
+    return Math.hypot(x, y);
+}
+/**
+ * Interpolates between two points
+ */
+function interpolate(p1, p2, t) {
+    return [p1[0] + (p2[0] - p1[0]) * t, p1[1] + (p2[1] - p1[1]) * t];
+}
+/**
+ * Splits a line into the pieces of a dash pattern measured in screen pixels at a zoom.
+ *
+ * Lengths are measured in Web Mercator pixels of 512 px tiles, so the dashes look the
+ * specified length on screen at `zoom`. The pattern continues across vertices.
+ *
+ * @param coords The vertices `[lng, lat]` in degrees
+ * @param dashLength The dash length in screen px
+ * @param gapLength The gap length in screen px
+ * @param zoom The zoom the lengths are measured at
+ * @returns The dashes, in order along the line. An empty array for fewer than 2 positions
+ */
+export function splitIntoDashes(coords, dashLength, gapLength, zoom) {
+    if (coords.length < 2)
+        return [];
+    const segments = [];
+    let currentDash = [];
+    let distanceInPattern = 0; // Current position within the pattern
+    let inDash = true; // Whether we are currently in a dash portion
+    // Add the first point
+    currentDash.push(coords[0]);
+    for (let i = 0; i < coords.length - 1; i++) {
+        const p1 = coords[i];
+        const p2 = coords[i + 1];
+        const segmentLength = calculateDistance(p1, p2, zoom);
+        if (segmentLength === 0)
+            continue;
+        let remainingInSegment = segmentLength;
+        let currentT = 0; // Current position within the segment (0-1)
+        while (remainingInSegment > 0) {
+            if (inDash) {
+                // Dash portion
+                const remainingInDash = dashLength - distanceInPattern;
+                if (remainingInSegment >= remainingInDash) {
+                    // The dash ends
+                    const t = currentT + remainingInDash / segmentLength;
+                    const point = interpolate(p1, p2, Math.min(t, 1));
+                    currentDash.push(point);
+                    // Store the dash
+                    if (currentDash.length >= 2) {
+                        segments.push({ coords: [...currentDash] });
+                    }
+                    currentDash = [];
+                    remainingInSegment -= remainingInDash;
+                    currentT = t;
+                    distanceInPattern = 0;
+                    inDash = false;
+                }
+                else {
+                    // The dash continues within the segment
+                    distanceInPattern += remainingInSegment;
+                    remainingInSegment = 0;
+                }
+            }
+            else {
+                // Gap portion
+                const remainingInGap = gapLength - distanceInPattern;
+                if (remainingInSegment >= remainingInGap) {
+                    // The gap ends
+                    const t = currentT + remainingInGap / segmentLength;
+                    const point = interpolate(p1, p2, Math.min(t, 1));
+                    currentDash = [point];
+                    remainingInSegment -= remainingInGap;
+                    currentT = t;
+                    distanceInPattern = 0;
+                    inDash = true;
+                }
+                else {
+                    // The gap continues within the segment
+                    distanceInPattern += remainingInSegment;
+                    remainingInSegment = 0;
+                }
+            }
+        }
+        // Add the end point of the segment (when we are in a dash portion)
+        if (inDash && currentDash.length > 0) {
+            currentDash.push(p2);
+        }
+    }
+    // Store the last dash
+    if (inDash && currentDash.length >= 2) {
+        segments.push({ coords: currentDash });
+    }
+    return segments;
+}
+/**
+ * Returns the dash and gap lengths in px that suit a line style at a line width.
+ *
+ * Unlike getDashPattern (preset) in shared/math, this computes dynamically from the stroke
+ * width.
+ *
+ * @param lineStyle The line style
+ * @param strokeWidth The line thickness at draw time (pixels)
+ * @returns [dashLength, gapLength], or null (for a solid line)
+ */
+export function getStrokeDashPattern(lineStyle, strokeWidth = 2) {
+    // The minimum gap at which round caps do not overlap
+    const minGap = strokeWidth + 1;
+    switch (lineStyle) {
+        case 'dashed':
+            // Dashed: longer dashes (4x the line width), moderate gaps (2x the line width)
+            return [Math.max(12, strokeWidth * 4), Math.max(minGap, strokeWidth * 2)];
+        case 'dotted':
+            // Dotted: short dots (nearly round), short gaps (about the line width)
+            return [Math.max(1, strokeWidth * 0.5), Math.max(minGap, strokeWidth * 1.2)];
+        default:
+            return null;
+    }
+}

package/dist/view/renderers/line/line-geometry.d.ts

@@ -0,0 +1,39 @@
+export declare const INSTANCE_STRIDE = 12;
+export declare const INSTANCE_BYTES: number;
+/**
+ * The upper bound on subdivision points
+ *
+ * When terrain is enabled, a single segment is split into at most this many parts to draw it.
+ * A long straight line with only two vertices (34km as measured) sinks into the terrain
+ * between subdivision points when split coarsely, so the line looks broken up like a dashed
+ * line. The upper bound was decided from that (34km / 512 = 66m, which lands at the same
+ * granularity as the subdivision step).
+ * The vertex buffer of the strip statically holds this upper bound, but (512+1)*2 vertices =
+ * 4KB, so it is negligible as a resource. The number of vertices actually drawn is determined
+ * from u_stations every time.
+ */
+export declare const MAX_LINE_STATIONS = 512;
+/**
+ * A guideline for how many post-split segments a single draw call may produce (a guard against
+ * a vertex-count blow-up)
+ *
+ * The number of subdivisions is determined by the longest segment in the batch, so a single
+ * long line mixed into a batch full of short lines makes the whole batch use the maximum
+ * subdivision. This caps that.
+ */
+export declare const LINE_STATION_BUDGET = 500000;
+/**
+ * The strip vertices shared by all instances (side, station)
+ *
+ * side: 1=left, -1=right / station: the index of the subdivision point along the segment
+ *
+ * On terrain, a segment sinks into valleys unless it is subdivided. Here the subdivision is
+ * expressed as "the station index in the vertex buffer plus the vertex count at draw time".
+ * Neither the coordinate texture of the segment nor the instance array is touched, so both
+ * retained batches and the partial update for a vertex drag (patchRetainedBatchCoords) keep
+ * working as they are.
+ *
+ * With u_stations = 1, drawing only 4 vertices gives stations 0,0,1,1, which is exactly the
+ * same triangle strip as before terrain was introduced.
+ */
+export declare const STATION_VERTICES: Float32Array<ArrayBuffer>;