@sakuzu/maplibre-gl-draw 1.0.0

package/dist/view/layer/frame-render.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The drawing stages of a frame
+ *
+ * Every slot draws its segment (`renderSegment`: the analytic drape of the segment, then the
+ * per-layer rendering once per copy of the world), and the last slot draws the foreground pass
+ * (`renderForeground`: the selection UI, the tentative geometry being drawn and the overlays).
+ * The state of the frame is built beforehand by frame-state.ts, and the GL state of the slot is
+ * set and restored through gl-state.ts.
+ */
+import type { Map as MapLibreMap } from 'maplibre-gl';
+import type { CustomFeatureHandler } from '../../extension/index.js';
+import type { Store } from '../../store/store.js';
+import type { FeatureCompanionRegistry } from '../feature-companion.js';
+import type { TerrainContext } from '../terrain/context.js';
+import type { SelectionScope } from '../ui/selection-scope.js';
+import type { DrapePlanner } from './drape-planner.js';
+import type { FrameState } from './frame-state.js';
+import { renderLayers } from './render.js';
+import type { Renderers } from './renderers.js';
+import type { StoreRetainedCache } from './store-retained.js';
+/**
+ * The datasets as the per-layer rendering takes them (the type is owned by
+ * render.ts, so this file does not read a type from display/)
+ */
+type RenderedDatasets = Parameters<typeof renderLayers>[10];
+/** What the drawing of a frame reads (the engine of the layer, while its GPU side exists) */
+export interface FrameRenderDeps {
+    gl: WebGL2RenderingContext;
+    renderers: Renderers;
+    map: MapLibreMap;
+    store: Store;
+    terrainContext: TerrainContext;
+    drape: DrapePlanner;
+    customRenderers: Map<string, CustomFeatureHandler['renderer']>;
+    featureCompanions: FeatureCompanionRegistry;
+    datasets?: RenderedDatasets;
+    storeRetainedCache: StoreRetainedCache | null;
+    selectionScope: SelectionScope;
+}
+/**
+ * The range [from, to) of the drape elements that corresponds to the segment of a slot
+ *
+ * The index of the pack being drawn (entryStarts) refers to the stacking order at the moment it
+ * was collected. Right after the order changes, the old pack keeps being drawn until the index
+ * of the new pack is built, so an entry of the current order may be missing from the index. In
+ * that case null is returned and the first slot draws every element (for a few frames they all
+ * come out below the external layers).
+ */
+export declare function drapeRangeOf(f: Pick<FrameState, 'segments' | 'layerOrder' | 'drapeEntryStarts' | 'drapeAboveStoreStart' | 'drapeElementsTotal'>, index: number): {
+    from: number;
+    to: number;
+} | null;
+/** One slot (the drape of its segment and the layer rendering) */
+export declare function renderSegment(deps: FrameRenderDeps, f: FrameState, index: number): void;
+/** The foreground pass (drawn by the last slot) */
+export declare function renderForeground(deps: FrameRenderDeps, f: FrameState): void;
+export {};

package/dist/view/layer/frame-render.js

@@ -0,0 +1,209 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { isInteractionBlocked } from '../../store/lock.js';
+import { setDrapePaintedDatasets, setQuadDrapeFrame, setTerrainRenderState, setTerrainShadeLight, setTerrainSurfacesFlattened, } from '../terrain/state.js';
+import { renderFollowedVertices, renderSelectionUI } from '../ui/selection-ui-drawer.js';
+import { applyDrapeGlState, applySegmentDepthState, applySegmentGlState, enterSymbolGlState, restoreSegmentGlState, resumeDrapeGlState, } from './gl-state.js';
+import { renderLayers } from './render.js';
+/** Makes the renderers draw on one copy of the world */
+function applyCopy(deps, copy) {
+    const r = deps.renderers;
+    r.shaderInitializer.setProjectionData(copy.projectionData);
+    r.shaderInitializer.applyOffsetUniforms(copy.offsetUniforms);
+    if (deps.terrainContext.renderState !== copy.terrainState) {
+        setTerrainRenderState(deps.terrainContext, copy.terrainState);
+    }
+}
+/**
+ * The range [from, to) of the drape elements that corresponds to the segment of a slot
+ *
+ * The index of the pack being drawn (entryStarts) refers to the stacking order at the moment it
+ * was collected. Right after the order changes, the old pack keeps being drawn until the index
+ * of the new pack is built, so an entry of the current order may be missing from the index. In
+ * that case null is returned and the first slot draws every element (for a few frames they all
+ * come out below the external layers).
+ */
+export function drapeRangeOf(f, index) {
+    const segment = f.segments[index];
+    const first = index === 0;
+    const last = index === f.segments.length - 1;
+    const order = f.layerOrder;
+    const startOf = (position) => position < order.length ? f.drapeEntryStarts.get(order[position]) : f.drapeAboveStoreStart;
+    let from = first ? 0 : startOf(segment.from);
+    let to = last ? f.drapeElementsTotal : startOf(segment.to);
+    if (from === undefined || to === undefined)
+        return null;
+    if (segment.from >= segment.to) {
+        // An empty segment (an order with nothing drawn by us). If it is both first and last, every
+        // element is drawn
+        from = first ? 0 : from;
+        to = last ? f.drapeElementsTotal : from;
+    }
+    return { from, to: Math.max(from, to) };
+}
+/**
+ * Sectioned drawing of the analytic drape (the element range of this slot, and the images
+ * interleaved into that range)
+ */
+function drawDrapeSegment(deps, f, index) {
+    const { gl, renderers: r, store, drape } = deps;
+    const drapeRenderer = drape.renderer;
+    if (!drapeRenderer || !f.drapeUsable)
+        return;
+    const first = index === 0;
+    const last = index === f.segments.length - 1;
+    if (!f.drapeReady) {
+        // The images that were to be interleaved between the sections are drawn here (the first
+        // slot only)
+        if (first) {
+            f.restoreBlendState();
+            for (const quadFeature of f.drapeFallbackQuads) {
+                r.featureDrawer.drawFeature(quadFeature, f.defaultProjectionData, f.zoom, store.getLayer(quadFeature.layerId) ?? undefined);
+            }
+        }
+        return;
+    }
+    let range = drapeRangeOf(f, index);
+    if (range === null) {
+        // A transient state where the index does not fit the current order. The first slot draws
+        // every element
+        if (!first)
+            return;
+        range = { from: 0, to: f.drapeElementsTotal };
+    }
+    const { from, to } = range;
+    applyDrapeGlState(gl);
+    const drawSegment = (paintFrom, paintTo, emitSelection) => {
+        for (const tileDraw of f.drapeTileDraws) {
+            drapeRenderer.drawTile(tileDraw.draw, tileDraw.projection, f.drapeLight, f.zoom, drape.sourceFactors, f.dpr, 1, { paintFrom, paintTo, emitSelection });
+        }
+    };
+    // Pick only the images that fall into the range of this slot (an image whose position equals
+    // the start of the range belongs to this slot; one that equals the end is picked only by the
+    // last slot)
+    let paintCursor = from;
+    for (const pendingQuad of f.pendingQuads) {
+        const inRange = pendingQuad.at >= from && (last ? pendingQuad.at <= to : pendingQuad.at < to);
+        if (!inRange)
+            continue;
+        if (pendingQuad.at > paintCursor) {
+            drawSegment(paintCursor, pendingQuad.at, false);
+            paintCursor = pendingQuad.at;
+        }
+        // Interleave the image. The quad drape draws with normal compositing (not premultiplied),
+        // so the blending is restored, and the depth test is left raised for the next section
+        // (keepDepthTest is true until the foreground). Afterwards the assumptions of the drape are
+        // established again.
+        f.restoreBlendState();
+        r.featureDrawer.drawFeature(pendingQuad.feature, f.defaultProjectionData, f.zoom, store.getLayer(pendingQuad.feature.layerId) ?? undefined);
+        resumeDrapeGlState(gl);
+    }
+    // The final section. The remaining elements, and on the last slot the selection highlight of
+    // every element, are drawn on top (the coverage of the selection accumulates regardless of
+    // the range, so raising it once is enough). Nothing is drawn when no element is left and
+    // there is no selection either (this skips a pointless evaluation of every pixel)
+    const hasDrapeSelection = last && drape.hasSelection;
+    if (to > paintCursor || hasDrapeSelection) {
+        drawSegment(paintCursor, to, last);
+    }
+    f.restoreBlendState();
+    // Back to the depth state of the layer rendering. What the drape could not paint (dashed
+    // lines, polygons with a dashed outline, the geometry being drawn, the features of
+    // extensions) is drawn next, by the vertex displacement path, and the terrain must hide it
+    // as it does in a frame without the drape. Symbols switch the depth test off themselves.
+    applySegmentDepthState(gl, deps.terrainContext, f);
+}
+/** One slot (the drape of its segment and the layer rendering) */
+export function renderSegment(deps, f, index) {
+    const { gl, renderers: r, store } = deps;
+    const segment = f.segments[index];
+    const first = index === 0;
+    const last = index === f.segments.length - 1;
+    applySegmentGlState(gl, deps.terrainContext, f);
+    applyCopy(deps, f.baseCopy);
+    drawDrapeSegment(deps, f, index);
+    // Per-layer rendering (only the segment of this slot), once per copy of the world in view
+    for (const copy of f.copies) {
+        applyCopy(deps, copy);
+        renderLayers(r, store, copy.features, f.selectedIdSet, copy.projectionData, f.zoom, deps.customRenderers, copy.customRendererContext, deps.featureCompanions, f.layerAwareRenderers, deps.datasets, f.useRetained ? (deps.storeRetainedCache ?? undefined) : undefined, f.restoreBlendState, { from: segment.from, to: segment.to, first, last }, copy.view);
+    }
+    applyCopy(deps, f.baseCopy);
+    if (!last)
+        restoreSegmentGlState(gl, f);
+}
+/** The foreground pass (drawn by the last slot) */
+export function renderForeground(deps, f) {
+    const { gl, renderers: r, store, map, terrainContext } = deps;
+    // From the selection UI onwards it is always drawn without depth (the symbols and the UI are
+    // not buried in the terrain)
+    enterSymbolGlState(gl);
+    // The depth is not restored even if a quad is drawn from here on
+    if (f.quadDrapeFrame)
+        f.quadDrapeFrame.keepDepthTest = false;
+    // Selection UI
+    // When the editing interaction is blocked (an effective lock, an interaction lock or
+    // read-only), only the selection box is drawn and no handles appear (the same look as
+    // locked). The box is shown even in read-only or under an interaction lock (so that a viewer
+    // also gets the on-map feedback of "what is selected", in the same grammar as the read-only
+    // mode of someone with edit permission).
+    const selectionLocked = f.selectedFeatures.some((feature) => isInteractionBlocked(feature, store));
+    const selectionUIDeps = {
+        selectionUIRenderer: r.selectionUIRenderer,
+        selectionHandlesRenderer: r.selectionHandlesRenderer,
+        pointInstanceRenderer: r.pointInstanceRenderer,
+        map,
+        scope: deps.selectionScope,
+    };
+    const tentative = store.getTentative();
+    const boxSelection = store.getBoxSelection();
+    // Once per copy of the world in view (the selection UI of a feature on the other side of the
+    // antimeridian is drawn on the copy the feature is drawn on)
+    for (const copy of f.copies) {
+        applyCopy(deps, copy);
+        renderSelectionUI(copy.selectedFeatures, f.zoom, copy.projectionData, selectionUIDeps, store.getDragState(), store.getSelectedVertices(), selectionLocked);
+        // The vertices that follow along when a shared vertex is moved (raised only during a
+        // drag). The features that follow are not selected, so they are drawn separately from the
+        // selection UI.
+        renderFollowedVertices(store.getFollowedVertices?.() ?? null, store, f.zoom, copy.projectionData, selectionUIDeps);
+        // Draw the vertices of the tentative in the foreground
+        if (tentative) {
+            r.tentativeRenderer.drawVertices(tentative, f.zoom);
+        }
+        // Draw the vertices of the layer-aware renderers in the foreground
+        for (const renderer of f.layerAwareRenderers) {
+            if (renderer.drawVertices) {
+                renderer.drawVertices(copy.projectionData, f.zoom, copy.customRendererContext);
+                f.restoreBlendState();
+            }
+        }
+        // Box selection UI (on the stored copy: its corners come from unproject around the
+        // camera)
+        //
+        // This is a rubber band on the screen, so pinning it to the ground would stop it from
+        // being a rectangle. Its renderers are built without the terrain (box-selection.ts), so it
+        // is drawn flat.
+        if (boxSelection && copy.lngShift === 0) {
+            r.boxSelectionRenderer.draw(boxSelection, f.defaultProjectionData, f.zoom);
+        }
+        // Drawing of the overlays that are not layer-aware
+        for (const renderer of f.otherRenderers) {
+            if (renderer.order === 'overlay' || renderer.order === 'foreground') {
+                renderer.draw(copy.projectionData, f.zoom, copy.customRendererContext);
+                f.restoreBlendState();
+            }
+        }
+    }
+    applyCopy(deps, f.baseCopy);
+    restoreSegmentGlState(gl, f);
+    // The report of the datasets being painted also lasts only for this frame
+    setDrapePaintedDatasets(terrainContext, null);
+    // The contract to draw flat lasts only for this frame (it is always restored so that it is
+    // not read from outside the rendering)
+    setTerrainSurfacesFlattened(terrainContext, false);
+    // The light lasts only for this frame as well
+    setTerrainShadeLight(terrainContext, null);
+    // The entry point of the quads lasts only for this frame (it is always removed so that it is
+    // not read from outside the rendering)
+    if (f.quadDrapeFrame)
+        setQuadDrapeFrame(terrainContext, null);
+}

package/dist/view/layer/frame-state.d.ts

@@ -0,0 +1,147 @@
+/**
+ * The state of one frame
+ *
+ * The first slot of a frame builds a `FrameState` (`buildFrameState`) and every slot of the
+ * frame reads it. It holds only results that do not depend on GL (maplibre resets the GL state
+ * for every slot): the zoom, the terrain state, the drape plan of the frame, the features of the
+ * immediate path, the selection, the overlay renderers and the copies of the world in view. The
+ * drawing of the slots is in frame-render.ts.
+ */
+import type { CustomRenderMethodInput, Map as MapLibreMap } from 'maplibre-gl';
+import type { CustomOverlayRenderer, CustomRendererDrawContext, LayerAwareOverlayRenderer } from '../../extension/index.js';
+import type { Store } from '../../store/store.js';
+import type { Feature } from '../../store/types.js';
+import { type OffsetUniforms } from '../shaders/helpers.js';
+import type { TerrainContext, TerrainRenderState } from '../terrain/context.js';
+import type { QuadDrapeFrame } from '../terrain/drape/quad.js';
+import { type DrapeLight } from '../terrain/drape/renderer.js';
+import type { DisplayListCache } from './display-list.js';
+import { type DrapePlanner, type DrapeTileDrawEntry, type MapTerrain, type PendingQuad } from './drape-planner.js';
+import type { RenderLayersView } from './render.js';
+import type { Renderers } from './renderers.js';
+import type { RenderSegment } from './slots.js';
+/**
+ * One copy of the world drawn in this frame
+ *
+ * Away from the antimeridian a frame draws one copy, the stored one (lngShift 0). A view
+ * across the antimeridian draws a second copy: the features stored on the other side of the
+ * line, moved by 360 degrees, through a virtual camera (the center moved by -lngShift and the
+ * matrix by +lngShift; `translateMatrixByLongitude` in shaders/helpers.ts). Everything that
+ * is not pinned per terrain tile goes through it: the layers, the datasets, the
+ * selection UI and the overlays. The analytic drape is drawn per terrain tile with the matrix
+ * maplibre gives each tile (the tiles carry their wrap), so it is drawn once.
+ */
+export interface CopyPass {
+    readonly lngShift: number;
+    /** The part of the view on this copy (undefined = the expanded viewport, one copy) */
+    readonly view: RenderLayersView | undefined;
+    readonly projectionData: CustomRenderMethodInput['defaultProjectionData'];
+    readonly offsetUniforms: OffsetUniforms;
+    readonly customRendererContext: CustomRendererDrawContext;
+    /** The features drawn in immediate mode on this copy */
+    readonly features: Feature[];
+    /** The selected features whose selection UI is drawn on this copy */
+    readonly selectedFeatures: Feature[];
+    /** The terrain state with the DEM atlas placed in the frame of the virtual camera */
+    readonly terrainState: TerrainRenderState;
+}
+/**
+ * Shared state of one frame
+ *
+ * The first slot builds it in the preparation and the following slots read it. maplibre resets
+ * the GL state for every slot, so only results that do not depend on GL are put here.
+ */
+export interface FrameState {
+    readonly segments: readonly RenderSegment[];
+    readonly layerOrder: readonly string[];
+    /** Number of the slot drawn most recently (a new frame when the next slot is at most this) */
+    lastIndex: number;
+    readonly shaderData: CustomRenderMethodInput['shaderData'];
+    readonly defaultProjectionData: CustomRenderMethodInput['defaultProjectionData'];
+    readonly getProjectionData: CustomRenderMethodInput['getProjectionData'];
+    readonly zoom: number;
+    readonly rawZoom: number;
+    readonly dpr: number;
+    readonly terrainState: TerrainRenderState;
+    readonly mapTerrain: MapTerrain;
+    readonly centerLngLat: [number, number];
+    readonly mainMatrixArray: number[];
+    readonly drapeUsable: boolean;
+    readonly wideFallback: boolean;
+    readonly useRetained: boolean;
+    readonly features: Feature[];
+    readonly selectedIdSet: Set<string>;
+    readonly selectedFeatures: Feature[];
+    readonly customRendererContext: CustomRendererDrawContext;
+    readonly layerAwareRenderers: LayerAwareOverlayRenderer[];
+    readonly otherRenderers: CustomOverlayRenderer[];
+    readonly quadDrapeFrame: QuadDrapeFrame | null;
+    readonly restoreBlendState: () => void;
+    /** Whether the drape can be drawn (the shaders and the plan are ready) */
+    readonly drapeReady: boolean;
+    readonly drapeLight: DrapeLight;
+    readonly drapeTileDraws: DrapeTileDrawEntry[];
+    readonly drapeElementsTotal: number;
+    readonly drapeAboveStoreStart: number;
+    readonly drapeEntryStarts: ReadonlyMap<string, number>;
+    readonly pendingQuads: PendingQuad[];
+    /**
+     * When the drape could not be built, a slot is needed to draw the images that were to be
+     * interleaved between the sections
+     */
+    readonly drapeFallbackQuads: Feature[];
+    /** The stored copy (lngShift 0); what everything outside the copies is drawn with */
+    readonly baseCopy: CopyPass;
+    /** The copies of the world in view (one, or two across the antimeridian) */
+    readonly copies: readonly CopyPass[];
+}
+/** The position of the camera: mercator x and y (0..1) and the altitude in meters */
+export type CameraPosition = readonly [number, number, number];
+/** What building a frame reads */
+export interface FrameBuildInput {
+    gl: WebGL2RenderingContext;
+    renderers: Renderers;
+    map: MapLibreMap;
+    store: Store;
+    terrainContext: TerrainContext;
+    displayList: DisplayListCache;
+    drape: DrapePlanner;
+    renderOptions: CustomRenderMethodInput;
+    /** The style zoom of the frame */
+    zoom: number;
+    /** The real zoom of the camera */
+    rawZoom: number;
+    dpr: number;
+    /** The terrain state of the frame (already set on the terrain context) */
+    terrainState: TerrainRenderState;
+    /** Whether the retained batches of the Store rendering exist */
+    retainedAvailable: boolean;
+    overlayRenderers: readonly CustomOverlayRenderer[];
+    segments: readonly RenderSegment[];
+}
+/**
+ * Builds the state of a frame (done once by the first slot)
+ *
+ * It sets up the shaders and the anchor projection of the frame, plans the analytic drape,
+ * picks the features of the immediate path and the selection, and plans the copies of the world.
+ */
+export declare function buildFrameState(input: FrameBuildInput): FrameState;
+/**
+ * Plans the copies of the world drawn in this frame
+ *
+ * One copy (the base one, unchanged) unless the view crosses the antimeridian. Across it,
+ * each copy gets its range of the view, the features of that range, the virtual camera
+ * (center and matrix moved by the copy's shift, computed in 64 bits) and the DEM atlas in the
+ * frame of that camera. The globe draws with maplibre's projectTile, which has no seam, so it
+ * keeps one copy.
+ */
+export declare function planCopies(baseCopy: CopyPass, options: {
+    renderers: Renderers | null;
+    displayList: DisplayListCache;
+    center: [number, number];
+    mainMatrixArray: number[];
+    useRetained: boolean;
+    excluded: Set<string> | null;
+    interleavedQuadIds: Set<string>;
+    transition: number;
+}): CopyPass[];