@sakuzu/maplibre-gl-draw 1.0.0

package/dist/view/layer/store-retained-coord-patch.js

@@ -0,0 +1,168 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { expandBBox } from './store-retained-bbox.js';
+/**
+ * Upper limit of the number of vertices that one update may put into the incremental update of
+ * the coordinate texture
+ *
+ * A change beyond this (moving vertices in bulk, cut and paste) rebuilds the whole chunk.
+ * The incremental update targets the case where "one vertex drag moves only a few points".
+ */
+export const MAX_PATCHED_VERTICES = 8;
+/**
+ * Extracts the line renderer if it supports partial updates of the coordinate texture
+ */
+export function asCoordPatcher(line) {
+    const candidate = line;
+    return typeof candidate.patchRetainedBatchCoords === 'function'
+        ? candidate
+        : null;
+}
+/**
+ * Computes the diff of a coordinate list (the indices of the vertices that moved)
+ *
+ * A vertex drag is an update where "the number of vertices is the same and only a few values
+ * differ". Anything else (vertices added or removed, many of them moved) cannot be applied as a
+ * diff, so null is returned.
+ *
+ * The comparison is done in a single pass. If the element references are the same, that vertex
+ * has not moved (the Store reuses the arrays of the vertices it does not change). The values are
+ * looked at only when the references differ.
+ *
+ * @param maxChanged Upper limit of the number of changed vertices allowed as a diff
+ * @returns The indices of the vertices that moved (an empty array when none moved). null when
+ *   the number of vertices differs or the upper limit is exceeded
+ */
+export function computeCoordinateDiff(prev, next, maxChanged) {
+    if (!Array.isArray(prev) || !Array.isArray(next))
+        return null;
+    if (prev.length !== next.length)
+        return null;
+    const changed = [];
+    for (let i = 0; i < next.length; i++) {
+        const a = prev[i];
+        const b = next[i];
+        if (a === b)
+            continue;
+        if (!a || !b)
+            return null;
+        if (a[0] === b[0] && a[1] === b[1])
+            continue;
+        // Beyond the upper limit it is not handled as a diff
+        if (changed.length >= maxChanged)
+            return null;
+        changed.push(i);
+    }
+    return changed;
+}
+/**
+ * Computes the "feature → position in the coordinate texture" of a line chunk
+ *
+ * The coordinate texture is packed with the coordinates in the order of the items returned by
+ * collectLineItems. Therefore this must count in the same order and with the same exclusion rule
+ * as collectLineItems (fewer than 2 vertices are not pushed).
+ *
+ * Only the types where one feature becomes one item and the coordinate list goes in as it is
+ * (LineString / Freehand) are recorded. A MultiLineString splits into several items and its
+ * indices interleave, so it is not a target of the diff (only the coordinate count is advanced).
+ */
+export function computeLineCoordSlots(features) {
+    const slots = new Map();
+    let offset = 0;
+    for (const feature of features) {
+        if (feature.type === 'MultiLineString') {
+            for (const part of feature.coordinates ?? []) {
+                if (!part || part.length < 2)
+                    continue;
+                offset += part.length;
+            }
+            continue;
+        }
+        const coords = feature.coordinates;
+        if (!coords || coords.length < 2)
+            continue;
+        if (feature.type === 'LineString' || feature.type === 'Freehand') {
+            slots.set(feature.id, { offset, count: coords.length });
+        }
+        offset += coords.length;
+    }
+    return slots;
+}
+/**
+ * Queues a vertex movement as a diff patch against the retained batch
+ *
+ * It can be queued only when all of the following hold. If even one of them fails, false is
+ * returned and the caller rebuilds the whole chunk (rebuilding too much still renders
+ * correctly).
+ *
+ * - A type whose coordinate list goes into the coordinate texture as one contiguous run
+ *   (LineString / Freehand)
+ * - No other item that affects the appearance (properties = the input of the style rules) has
+ *   changed
+ * - The number of vertices is unchanged and between 1 and MAX_PATCHED_VERTICES vertices moved
+ * - The chunk it belongs to has a retained line batch and is not waiting for a rebuild
+ * - The renderer used for drawing supports partial updates of the coordinate texture
+ *
+ * The drag being committed (up) does not trigger another rebuild. The patch queued by the last
+ * movement becomes the committed value as it is.
+ *
+ * @param chunk The chunk that carries the feature (undefined when there is none)
+ * @param line The line renderer used most recently (null before the first draw)
+ */
+export function queueCoordPatch(chunk, feature, previous, line) {
+    if (feature.type !== 'LineString' && feature.type !== 'Freehand')
+        return false;
+    // properties is the input of the style rules, so a change there can change the color
+    if (previous.properties !== feature.properties)
+        return false;
+    if (!chunk)
+        return false;
+    if (chunk.kind !== 'line' || !chunk.line || chunk.dirty || !chunk.lineOffsets)
+        return false;
+    const slot = chunk.lineOffsets.get(feature.id);
+    if (!slot)
+        return false;
+    const coords = feature.coordinates;
+    // If the vertex count differs from when the index table was built, the positions of the
+    // following features are off as well
+    if (!Array.isArray(coords) || coords.length !== slot.count)
+        return false;
+    const changed = computeCoordinateDiff(previous.coordinates, coords, MAX_PATCHED_VERTICES);
+    if (!changed)
+        return false;
+    // An update where no vertex moved (a change of locked, for example) is not treated as a diff;
+    // the chunk is rebuilt as before (erring on the conservative side)
+    if (changed.length === 0)
+        return false;
+    // With a renderer that has no partial update, a queued diff could never be applied
+    if (!line || !asCoordPatcher(line))
+        return false;
+    const patches = chunk.pendingCoordPatches ?? [];
+    chunk.pendingCoordPatches = patches;
+    for (const i of changed) {
+        const coord = coords[i];
+        patches.push({ coordIndex: slot.offset + i, lngLat: [coord[0], coord[1]] });
+        chunk.bbox = expandBBox(chunk.bbox, coord);
+    }
+    return true;
+}
+/**
+ * Applies the queued vertex diff to the coordinate texture
+ *
+ * It is not called for a chunk thinned away off-screen, but the patches stay queued, so they
+ * are all applied on the first frame where the chunk comes into view.
+ */
+export function flushCoordPatches(chunk, line) {
+    const patches = chunk.pendingCoordPatches;
+    if (!patches || !chunk.line)
+        return;
+    chunk.pendingCoordPatches = null;
+    const patcher = asCoordPatcher(line);
+    if (!patcher) {
+        // Safety net for the case where the renderer was swapped for one without partial updates.
+        // This frame keeps the stale picture, but the next frame rebuilds it.
+        chunk.dirty = true;
+        return;
+    }
+    patcher.patchRetainedBatchCoords(chunk.line, patches);
+}

package/dist/view/layer/store-retained-immediate.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Immediate-mode drawing of the chunks that cannot be retained
+ *
+ * Dashed lines, images, point shapes without instancing support, custom types and features with
+ * a companion are drawn one at a time through the immediate-mode draw target, in the same order
+ * as the layer loop of render.ts.
+ */
+import type { ProjectionData } from 'maplibre-gl';
+import type { CustomFeatureHandler, CustomRendererDrawContext } from '../../extension/index.js';
+import type { Store } from '../../store/store.js';
+import type { Feature, Layer } from '../../store/types.js';
+import { type FeatureCompanionRegistry } from '../feature-companion.js';
+import type { RetainedRendererSet } from '../renderers/retained.js';
+/**
+ * Draw target used when falling back to immediate mode (the same shape as BatchManager)
+ */
+export interface StoreImmediateTarget {
+    beginFrame(projectionData: ProjectionData, zoom: number, layer?: Layer): void;
+    processFeature(feature: Feature, isSelected: boolean): boolean;
+    endFrame(): void;
+}
+/**
+ * Dependencies of drawLayer
+ */
+export interface StoreRetainedDrawDeps {
+    /** The full set of renderers of retained mode */
+    renderers: RetainedRendererSet;
+    /** Immediate-mode draw target that draws the features which cannot be retained */
+    batchManager: StoreImmediateTarget;
+    /** Renderers of the custom feature types (type name → renderer) */
+    customRenderers: Map<string, CustomFeatureHandler['renderer']>;
+    /** Draw context passed to a custom renderer */
+    customRendererContext: CustomRendererDrawContext;
+    /** Providers of companion drawing and companion hits (those of this draw instance) */
+    companions: FeatureCompanionRegistry;
+    /**
+     * Returns the set of feature ids inside the expanded viewport (a spatial index query)
+     *
+     * Used to thin immediate chunks per feature. It is not called in a frame that draws no
+     * immediate chunk at all (the caller must memoize it within the frame). When omitted, an
+     * immediate chunk is thinned by the chunk bbox alone.
+     */
+    getVisibleIds?: () => ReadonlySet<string>;
+    /**
+     * Re-establishes the blend state of our own rendering (a wrapper around `applyDrawBlendState`)
+     *
+     * The renderer of a custom feature type is an external implementation and may come back having
+     * rewritten the blend function for its own purposes. Left alone, everything drawn later in the
+     * same frame would be composited wrongly, so it is called right after control comes back.
+     * When omitted nothing is re-established (the path of tests that have no GL).
+     */
+    restoreBlendState?: () => void;
+}
+/**
+ * Draws a list of features in immediate mode
+ *
+ * It draws with the same steps as the current immediate mode (the layer loop of render.ts).
+ * A custom type is drawn after the batch has been flushed, to keep the draw order.
+ *
+ * @param store Where the features are looked up again (hidden ones are skipped)
+ * @param visibleIds Feature ids inside the expanded viewport (no thinning when omitted)
+ */
+export declare function drawFeaturesImmediate(store: Store, featureIds: string[], layer: Layer | undefined, projectionData: ProjectionData, zoom: number, deps: StoreRetainedDrawDeps, visibleIds?: ReadonlySet<string>): void;

package/dist/view/layer/store-retained-immediate.js

@@ -0,0 +1,49 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { isLocallyHidden } from '../../store/local-visibility.js';
+import { drawFeatureCompanionsInFrame, } from '../feature-companion.js';
+/**
+ * Draws a list of features in immediate mode
+ *
+ * It draws with the same steps as the current immediate mode (the layer loop of render.ts).
+ * A custom type is drawn after the batch has been flushed, to keep the draw order.
+ *
+ * @param store Where the features are looked up again (hidden ones are skipped)
+ * @param visibleIds Feature ids inside the expanded viewport (no thinning when omitted)
+ */
+export function drawFeaturesImmediate(store, featureIds, layer, projectionData, zoom, deps, visibleIds) {
+    const { batchManager, customRenderers, customRendererContext } = deps;
+    batchManager.beginFrame(projectionData, zoom, layer);
+    for (const id of featureIds) {
+        if (visibleIds && !visibleIds.has(id))
+            continue;
+        const feature = store.getFeature(id);
+        if (!feature?.visible || isLocallyHidden(feature, store))
+            continue;
+        // Companion drawing (feature companion): drawn right before the feature itself, that is,
+        // one z below it. classifyFeature splits a feature that has a companion out into an
+        // immediate chunk, so going through here makes the z order in retained mode identical to
+        // immediate mode.
+        drawFeatureCompanionsInFrame(deps.companions, feature, batchManager, projectionData, zoom, layer, customRendererContext, deps.restoreBlendState);
+        const customRenderer = customRenderers.get(feature.type);
+        if (customRenderer) {
+            // To keep the draw order (painter's algorithm), the core batch that has accumulated is
+            // flushed first and only then the custom feature is drawn immediately.
+            batchManager.endFrame();
+            customRenderer.draw({
+                id: feature.id,
+                type: feature.type,
+                coordinates: feature.coordinates,
+                properties: feature.properties,
+                style: feature.style,
+            }, projectionData, zoom, customRendererContext);
+            // Re-establish the blend state that the external renderer may have rewritten
+            deps.restoreBlendState?.();
+            batchManager.beginFrame(projectionData, zoom, layer);
+        }
+        else {
+            batchManager.processFeature(feature, false);
+        }
+    }
+    batchManager.endFrame();
+}

package/dist/view/layer/store-retained-invalidation.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Detection of the changes that invalidate every retained chunk
+ *
+ * Some inputs of the retained batches do not arrive as a change of the Store: the set of locally
+ * hidden features (updated in place), the registry of companion drawing and the generations of
+ * the terrain. They are checked once per frame, and any change discards the whole cache.
+ */
+import type { Layer, StateChanges } from '../../store/types.js';
+import type { FeatureCompanionRegistry } from '../feature-companion.js';
+import type { TerrainContext } from '../terrain/context.js';
+/**
+ * Snapshots of the inputs that invalidate every chunk
+ *
+ * Each method records the current value and reports whether it changed since the previous call.
+ * The first call only records (there is no cache yet, so nothing has to be discarded).
+ */
+export declare class RetainedInvalidationWatch {
+    /** Previous snapshot of the set of locally hidden features */
+    private hiddenSnapshot;
+    private hiddenSnapshotReady;
+    /**
+     * Previous generation of the companion drawing (feature companion) registry
+     *
+     * Registering or unregistering a provider can change the result of classifyFeature, so the
+     * cached classification is discarded whenever the generation changes.
+     */
+    private companionGeneration;
+    /**
+     * Previous generation of the terrain subdivision
+     *
+     * The fill and the outline of a polygon bake the subdivision step into the vertex data. When
+     * the step changes (terrain switched on or off, a zoom threshold crossed) they have to be
+     * rebuilt. A line is split on the GPU side and bakes nothing, so it would not need a rebuild,
+     * but the generation only changes on a zoom crossing or when terrain is switched, so discarding
+     * everything is acceptable.
+     */
+    private terrainGeneration;
+    /**
+     * Previous generation of the cells of the globe
+     *
+     * On the globe the fill and the outline of a polygon bake the cut along the Mercator plane
+     * (`view/globe-subdivision.ts`). The generation changes when the globe starts or stops being
+     * drawn and when the zoom crosses an integer that changes a cell.
+     */
+    private globeGeneration;
+    /**
+     * Generation of the baked anchor elevation (-1 when not built yet)
+     *
+     * A point batch bakes the ground elevation into each instance. Unless it is rebuilt when a DEM
+     * tile arrives and the elevation changes, only the points are left behind at the old height.
+     */
+    private anchorElevationGeneration;
+    /**
+     * Whether the set of locally hidden features changed
+     *
+     * The Store updates the same Set in place, so a reference comparison is impossible. The hidden
+     * set is usually small, so it is compared by count first and then by every element.
+     */
+    locallyHiddenChanged(current: ReadonlySet<string>): boolean;
+    /**
+     * Whether providers of companion drawing were added or removed
+     *
+     * When the registrations change, the classification "a feature with a companion goes into an
+     * immediate chunk" can change. Comparing the generation is a single integer, so with no change
+     * the cost per frame is effectively zero.
+     */
+    companionsChanged(companions: FeatureCompanionRegistry): boolean;
+    /**
+     * Whether a generation of the terrain changed
+     *
+     * There are three things to look at: the subdivision step of the terrain and the cells of the
+     * globe (the split points of polygons and lines change), and the anchor elevation (the ground
+     * height baked into the points changes). DEM tiles arrive asynchronously, so the last advances
+     * several times after the first frame.
+     */
+    terrainChanged(terrain: TerrainContext): boolean;
+    /**
+     * Forgets the snapshot of the hidden set (the next call records it again)
+     *
+     * The generations are kept: a disposed cache still knows the generations it last saw.
+     */
+    resetLocallyHidden(): void;
+}
+/**
+ * Whether an update of a layer changed only its opacity
+ *
+ * The opacity is applied at draw time (a uniform of the retained batches, a factor of the drape
+ * source), so such an update needs no rebuild. Any other field that differs, including one this
+ * function does not know, counts as a change (the safe side).
+ */
+export declare function isOpacityOnlyLayerChange(previous: Layer, layer: Layer): boolean;
+/**
+ * Whether a change of the layers consists only of opacity updates (nothing created, deleted or
+ * reordered, and every update is {@link isOpacityOnlyLayerChange})
+ */
+export declare function isOpacityOnlyLayersChange(layers: NonNullable<StateChanges['layers']>): boolean;

package/dist/view/layer/store-retained-invalidation.js

@@ -0,0 +1,192 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { getAnchorElevationGeneration } from '../terrain/anchor.js';
+/**
+ * Snapshots of the inputs that invalidate every chunk
+ *
+ * Each method records the current value and reports whether it changed since the previous call.
+ * The first call only records (there is no cache yet, so nothing has to be discarded).
+ */
+export class RetainedInvalidationWatch {
+    constructor() {
+        /** Previous snapshot of the set of locally hidden features */
+        Object.defineProperty(this, "hiddenSnapshot", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Set()
+        });
+        Object.defineProperty(this, "hiddenSnapshotReady", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        /**
+         * Previous generation of the companion drawing (feature companion) registry
+         *
+         * Registering or unregistering a provider can change the result of classifyFeature, so the
+         * cached classification is discarded whenever the generation changes.
+         */
+        Object.defineProperty(this, "companionGeneration", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: -1
+        });
+        /**
+         * Previous generation of the terrain subdivision
+         *
+         * The fill and the outline of a polygon bake the subdivision step into the vertex data. When
+         * the step changes (terrain switched on or off, a zoom threshold crossed) they have to be
+         * rebuilt. A line is split on the GPU side and bakes nothing, so it would not need a rebuild,
+         * but the generation only changes on a zoom crossing or when terrain is switched, so discarding
+         * everything is acceptable.
+         */
+        Object.defineProperty(this, "terrainGeneration", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: -1
+        });
+        /**
+         * Previous generation of the cells of the globe
+         *
+         * On the globe the fill and the outline of a polygon bake the cut along the Mercator plane
+         * (`view/globe-subdivision.ts`). The generation changes when the globe starts or stops being
+         * drawn and when the zoom crosses an integer that changes a cell.
+         */
+        Object.defineProperty(this, "globeGeneration", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: -1
+        });
+        /**
+         * Generation of the baked anchor elevation (-1 when not built yet)
+         *
+         * A point batch bakes the ground elevation into each instance. Unless it is rebuilt when a DEM
+         * tile arrives and the elevation changes, only the points are left behind at the old height.
+         */
+        Object.defineProperty(this, "anchorElevationGeneration", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: -1
+        });
+    }
+    /**
+     * Whether the set of locally hidden features changed
+     *
+     * The Store updates the same Set in place, so a reference comparison is impossible. The hidden
+     * set is usually small, so it is compared by count first and then by every element.
+     */
+    locallyHiddenChanged(current) {
+        if (!this.hiddenSnapshotReady) {
+            this.hiddenSnapshot = new Set(current);
+            this.hiddenSnapshotReady = true;
+            return false;
+        }
+        if (current.size === this.hiddenSnapshot.size) {
+            let same = true;
+            for (const id of current) {
+                if (!this.hiddenSnapshot.has(id)) {
+                    same = false;
+                    break;
+                }
+            }
+            if (same)
+                return false;
+        }
+        this.hiddenSnapshot = new Set(current);
+        return true;
+    }
+    /**
+     * Whether providers of companion drawing were added or removed
+     *
+     * When the registrations change, the classification "a feature with a companion goes into an
+     * immediate chunk" can change. Comparing the generation is a single integer, so with no change
+     * the cost per frame is effectively zero.
+     */
+    companionsChanged(companions) {
+        const generation = companions.generation();
+        if (generation === this.companionGeneration)
+            return false;
+        // On the first time there is no cache at all, so nothing has to be discarded
+        const first = this.companionGeneration === -1;
+        this.companionGeneration = generation;
+        return !first;
+    }
+    /**
+     * Whether a generation of the terrain changed
+     *
+     * There are three things to look at: the subdivision step of the terrain and the cells of the
+     * globe (the split points of polygons and lines change), and the anchor elevation (the ground
+     * height baked into the points changes). DEM tiles arrive asynchronously, so the last advances
+     * several times after the first frame.
+     */
+    terrainChanged(terrain) {
+        let changed = false;
+        const generation = terrain.renderState.generation;
+        if (generation !== this.terrainGeneration) {
+            const first = this.terrainGeneration === -1;
+            this.terrainGeneration = generation;
+            if (!first)
+                changed = true;
+        }
+        if (terrain.globeGeneration !== this.globeGeneration) {
+            const first = this.globeGeneration === -1;
+            this.globeGeneration = terrain.globeGeneration;
+            if (!first)
+                changed = true;
+        }
+        const anchorGeneration = getAnchorElevationGeneration(terrain);
+        if (anchorGeneration !== this.anchorElevationGeneration) {
+            const first = this.anchorElevationGeneration === -1;
+            this.anchorElevationGeneration = anchorGeneration;
+            if (!first)
+                changed = true;
+        }
+        return changed;
+    }
+    /**
+     * Forgets the snapshot of the hidden set (the next call records it again)
+     *
+     * The generations are kept: a disposed cache still knows the generations it last saw.
+     */
+    resetLocallyHidden() {
+        this.hiddenSnapshot = new Set();
+        this.hiddenSnapshotReady = false;
+    }
+}
+/**
+ * Whether an update of a layer changed only its opacity
+ *
+ * The opacity is applied at draw time (a uniform of the retained batches, a factor of the drape
+ * source), so such an update needs no rebuild. Any other field that differs, including one this
+ * function does not know, counts as a change (the safe side).
+ */
+export function isOpacityOnlyLayerChange(previous, layer) {
+    if (previous.opacity === layer.opacity)
+        return false;
+    const keys = new Set([...Object.keys(previous), ...Object.keys(layer)]);
+    for (const key of keys) {
+        if (key === 'opacity')
+            continue;
+        if (previous[key] !== layer[key])
+            return false;
+    }
+    return true;
+}
+/**
+ * Whether a change of the layers consists only of opacity updates (nothing created, deleted or
+ * reordered, and every update is {@link isOpacityOnlyLayerChange})
+ */
+export function isOpacityOnlyLayersChange(layers) {
+    if (layers.created?.length || layers.deleted?.length || layers.orderChanged)
+        return false;
+    const updated = layers.updated ?? [];
+    if (updated.length === 0)
+        return false;
+    return updated.every(({ layer, previous }) => isOpacityOnlyLayerChange(previous, layer));
+}