@sakuzu/maplibre-gl-draw 1.0.0

package/dist/display/provider.js

@@ -0,0 +1,342 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { normalizeDisplayFeature } from './types.js';
+/** Maximum zoom stage of the tile coordinates */
+const MAX_TILE_ZOOM = 22;
+/** Upper limit of the latitude that Web Mercator can express */
+const MAX_MERCATOR_LAT = 85.0511287798066;
+/** Clamps a value into a range */
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+/**
+ * Computes the zoom stage (floored to an integer and clamped into 0-22)
+ *
+ * @internal
+ */
+export function toZoomStage(zoom) {
+    if (!Number.isFinite(zoom))
+        return 0;
+    return clamp(Math.floor(zoom), 0, MAX_TILE_ZOOM);
+}
+/**
+ * Computes the tile X coordinate from a longitude
+ *
+ * @internal
+ */
+export function lngToTileX(lng, z) {
+    const n = 2 ** z;
+    return clamp(Math.floor(((clamp(lng, -180, 180) + 180) / 360) * n), 0, n - 1);
+}
+/**
+ * Computes the tile Y coordinate from a latitude
+ *
+ * @internal
+ */
+export function latToTileY(lat, z) {
+    const n = 2 ** z;
+    const clamped = clamp(lat, -MAX_MERCATOR_LAT, MAX_MERCATOR_LAT);
+    const rad = (clamped * Math.PI) / 180;
+    const y = ((1 - Math.log(Math.tan(rad) + 1 / Math.cos(rad)) / Math.PI) / 2) * n;
+    return clamp(Math.floor(y), 0, n - 1);
+}
+/**
+ * Computes the longitude of the western edge of a tile X coordinate
+ *
+ * @internal
+ */
+export function tileXToLng(x, z) {
+    const n = 2 ** z;
+    return (x / n) * 360 - 180;
+}
+/**
+ * Computes the latitude of the northern edge of a tile Y coordinate
+ *
+ * @internal
+ */
+export function tileYToLat(y, z) {
+    const n = 2 ** z;
+    const t = Math.PI * (1 - (2 * y) / n);
+    return (Math.atan(Math.sinh(t)) * 180) / Math.PI;
+}
+/**
+ * Rounds a displayed range to a range of tile coordinates
+ *
+ * @internal
+ */
+export function toTileRange(bounds, zoom) {
+    const z = toZoomStage(zoom);
+    return {
+        z,
+        minX: lngToTileX(bounds.minX, z),
+        maxX: lngToTileX(bounds.maxX, z),
+        // Tile Y gets smaller towards the north, so the latitudes and minY / maxY are inverted
+        minY: latToTileY(bounds.maxY, z),
+        maxY: latToTileY(bounds.minY, z),
+    };
+}
+/**
+ * Cache key of a tile range
+ *
+ * @internal
+ */
+export function tileRangeKey(range) {
+    return `${range.z}/${range.minX}/${range.minY}/${range.maxX}/${range.maxY}`;
+}
+/**
+ * Computes the bbox that covers a tile range (the range passed to the provider)
+ *
+ * A range rounded to the tile boundaries is passed, so a request with the same key always gets
+ * the same bbox.
+ *
+ * @internal
+ */
+export function tileRangeBounds(range) {
+    return {
+        minX: tileXToLng(range.minX, range.z),
+        maxX: tileXToLng(range.maxX + 1, range.z),
+        minY: tileYToLat(range.maxY + 1, range.z),
+        maxY: tileYToLat(range.minY, range.z),
+    };
+}
+/**
+ * Default number of entries kept in the cache
+ *
+ * @internal
+ */
+export const DEFAULT_TILE_CACHE_SIZE = 32;
+/**
+ * Cache that keeps the results of the provider under a tile key
+ *
+ * Once the maximum count is exceeded, the least recently used key is discarded (LRU).
+ *
+ * @internal
+ */
+export class TileFeatureCache {
+    constructor(maxSize = DEFAULT_TILE_CACHE_SIZE) {
+        Object.defineProperty(this, "entries", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        Object.defineProperty(this, "maxSize", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.maxSize = Math.max(1, maxSize);
+    }
+    /** Number of keys held */
+    get size() {
+        return this.entries.size;
+    }
+    /** Takes out the result of a key (the key taken out counts as most recently used) */
+    get(key) {
+        const value = this.entries.get(key);
+        if (!value)
+            return undefined;
+        this.entries.delete(key);
+        this.entries.set(key, value);
+        return value;
+    }
+    /** Stores the result of a key */
+    set(key, features) {
+        if (this.entries.has(key)) {
+            this.entries.delete(key);
+        }
+        this.entries.set(key, features);
+        while (this.entries.size > this.maxSize) {
+            const oldest = this.entries.keys().next();
+            if (oldest.done)
+                break;
+            this.entries.delete(oldest.value);
+        }
+    }
+    /** Empties the cache */
+    clear() {
+        this.entries.clear();
+    }
+}
+/**
+ * The receiver of the loading and the updates of one dataset with a provider
+ *
+ * The range is handled through a key rounded to a zoom stage plus tile coordinates. Nothing
+ * happens when it equals the key already applied; when it is in the cache it is applied at once;
+ * otherwise the call is debounced. While a fetch is in flight, the previous result keeps being
+ * shown. Only the response of the last request is applied.
+ *
+ * @internal
+ */
+export class DisplayProviderLoader {
+    constructor(provider, host) {
+        Object.defineProperty(this, "provider", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: provider
+        });
+        Object.defineProperty(this, "host", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: host
+        });
+        Object.defineProperty(this, "tileCache", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new TileFeatureCache()
+        });
+        Object.defineProperty(this, "timer", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        /** The key waiting for the debounce */
+        Object.defineProperty(this, "pendingKey", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        /** The key already applied to the display */
+        Object.defineProperty(this, "appliedKey", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        /** Serial number of the issued requests (so that only the last one is applied) */
+        Object.defineProperty(this, "requestSeq", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        /**
+         * Generation of the cache
+         *
+         * It is advanced by invalidate. A response in flight across the discard is thrown away by this
+         * mark before it is written back into the cache (with the serial number alone the response
+         * would be dropped only after it entered tileCache, so a stale result would remain).
+         */
+        Object.defineProperty(this, "cacheGeneration", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        /** The serial number of the request whose response is awaited (null = none in flight) */
+        Object.defineProperty(this, "awaitedSeq", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "disposed", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+    }
+    /**
+     * Whether a call is waiting for its debounce, or the response of the last call has not
+     * arrived yet (the features shown will change without anything else happening)
+     */
+    get busy() {
+        return !this.disposed && (this.timer !== null || this.awaitedSeq !== null);
+    }
+    /** Schedules the call of the provider for a displayed range */
+    schedule(bounds, zoom) {
+        if (this.disposed)
+            return;
+        const range = toTileRange(bounds, zoom);
+        const key = tileRangeKey(range);
+        if (key === this.appliedKey) {
+            // It came back to the range being shown. The pending call is cancelled
+            this.cancelPending();
+            return;
+        }
+        const cached = this.tileCache.get(key);
+        if (cached) {
+            this.cancelPending();
+            this.appliedKey = key;
+            this.host.apply(cached);
+            return;
+        }
+        if (key === this.pendingKey)
+            return;
+        this.cancelPending();
+        this.pendingKey = key;
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            this.pendingKey = null;
+            this.run(range, key, zoom);
+        }, this.host.debounceMs);
+    }
+    /**
+     * Discards the cache and fetches the displayed range again
+     *
+     * A response in flight reaches neither the cache nor the display.
+     */
+    invalidate(bounds, zoom) {
+        if (this.disposed)
+            return;
+        this.cacheGeneration++;
+        this.tileCache.clear();
+        // Fetch again even for the same range (the early return is cleared)
+        this.appliedKey = null;
+        this.cancelPending();
+        this.schedule(bounds, zoom);
+    }
+    /** Stops the timer and empties the cache. A response in flight is not applied afterwards */
+    dispose() {
+        this.disposed = true;
+        this.cancelPending();
+        this.tileCache.clear();
+    }
+    /** Calls the provider and applies only the response of the last request */
+    run(range, key, zoom) {
+        if (this.disposed)
+            return;
+        const seq = ++this.requestSeq;
+        const generation = this.cacheGeneration;
+        const bounds = tileRangeBounds(range);
+        this.awaitedSeq = seq;
+        const settle = () => {
+            if (this.awaitedSeq === seq)
+                this.awaitedSeq = null;
+        };
+        void this.provider(bounds, zoom).then((features) => {
+            settle();
+            if (this.disposed)
+                return;
+            // A response in flight across the discard is thrown away with its contents. It does not
+            // enter the cache either
+            if (generation !== this.cacheGeneration)
+                return;
+            const normalized = features.map(normalizeDisplayFeature);
+            this.tileCache.set(key, normalized);
+            // Even when an old response overtakes a new one, nothing but the last request is applied
+            if (seq !== this.requestSeq)
+                return;
+            this.appliedKey = key;
+            this.host.apply(normalized);
+        }, (error) => {
+            settle();
+            console.error(`Dataset "${this.host.id}": provider failed`, error);
+        });
+    }
+    /** Cancels the call waiting for the debounce */
+    cancelPending() {
+        if (this.timer !== null) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        this.pendingKey = null;
+    }
+}

package/dist/display/retained.d.ts

@@ -0,0 +1,40 @@
+import type { RetainedRendererSet } from '../view/renderers/retained.js';
+/**
+ * The job that builds the retained batches of a chunk in slices
+ *
+ * What cannot be finished in one frame is advanced by the budget of the frame and handed on. The
+ * caller keeps drawing the batches of the previous version until it is finished
+ * (`display/chunk-set.ts`). It is built the same way as the one-shot build
+ * (`buildChunkBatches`); only the unit of bundling differs.
+ */
+export interface ChunkBuildJob {
+    /**
+     * Advances until the deadline
+     *
+     * At least one step is taken even when the budget is exhausted (otherwise it would never end).
+     *
+     * @returns Whether it is finished
+     */
+    step(deadline: number, now: () => number): boolean;
+    /** The finished batches (null when unfinished or when the build failed) */
+    take(): DisplayChunkBatches | null;
+    /** Discards the GPU resources built so far */
+    dispose(renderers: RetainedRendererSet): void;
+}
+/**
+ * Rebuilds only the point part of a chunk: its point batches and its points drawn in immediate
+ * mode (`pointFallback`)
+ *
+ * The polygons, the lines and `fallback` are not touched at all. Two things change the points
+ * alone: the anchor elevations baked into the point instances when DEM tiles arrive, and the
+ * rows the collision thinning draws (it only ever removes points). Rebuilding the polygons for
+ * them would re-triangulate every polygon through earcut, so the point part is rebuilt on its
+ * own; its cost is a walk over the rows of the chunk plus the packing of the points it draws.
+ *
+ * @param collector A collector of the points of the chunk (`pointsOnly`). The dataset uses
+ *   the same code as the build, so the appearance at build time and at re-bake time cannot
+ *   disagree
+ * @returns true when they could be rebuilt. When the retained-mode renderers do not have their
+ *   shaders yet (the build failed) false is returned and the old point part is left as it is
+ */
+export declare function rebuildChunkPoints(batches: DisplayChunkBatches, collector: ChunkCollector, renderers: RetainedRendererSet, origin: [number, number]): boolean;