@sakuzu/maplibre-gl-draw 1.0.0

package/dist/view/terrain/context.js

@@ -0,0 +1,437 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * The owner of the terrain rendering state (one per draw instance)
+ *
+ * The terrain state mixes two kinds of things: "values valid only for that frame" and
+ * "records carried across frames". The former alone would be fine as a module global (the
+ * same practice as `shaders/frame.ts`), but putting the latter in a global breaks when a page
+ * has several rendering instances.
+ *
+ * How it actually broke: when a page has several maps (the main one, a thumbnail, a print
+ * preview and so on) each has its own Map and CustomLayer. The subdivision generation counter
+ * counts from 0 per CustomLayer, yet the place that value was written to was a single global.
+ * Retained batches (`layer/store-retained.ts`) decide whether to re-bake by "the global
+ * generation vs their own record", so whenever the counters of two instances happened to
+ * coincide the change was invisible and flat geometry baked before the terrain came alive was
+ * never rebuilt. The subdivision cache (`cache/terrain-fill.ts`) was shared by feature id as
+ * well, so when the generations coincided by chance it returned triangles subdivided with
+ * another instance's step (the shape where only the summit becomes a tent).
+ *
+ * So the whole state is collected into this class and each CustomLayer owns one. There is no
+ * module-level "current" context: every reader (state.ts / anchor.ts / occlusion.ts /
+ * polygon.ts) takes the context explicitly. The renderers of a CustomLayer receive their
+ * instance's context at construction, extension renderers receive it in the draw context
+ * (`CustomRendererDrawContext.terrain`), hit testing uses the anchor projection bound per map
+ * (`installAnchorProjector`), and plugins use the projection bound to their instance
+ * (`PluginContext.projectAnchor`). A read from outside rendering therefore always sees its own
+ * instance, never "the instance drawn last".
+ */
+import { TerrainFillCache } from '../cache/terrain-fill.js';
+import { TerrainCoverage } from './ground.js';
+/** The state when the terrain is disabled */
+export const INACTIVE_TERRAIN_STATE = {
+    active: false,
+    atlasTexture: null,
+    atlasRect: [0, 0, 1, 1],
+    atlasSize: [1, 1],
+    elevationScale: 0,
+    liftMeters: 0,
+    stepMeters: 0,
+    stepGrid: 0,
+    tessellationRegion: null,
+    tessellationTiling: null,
+    generation: 0,
+};
+/** The initial diagnostic values */
+export const INITIAL_DRAPE_DEBUG = {
+    used: false,
+    reason: 'not-evaluated',
+    featureCount: 0,
+    edgeCount: 0,
+    tileCount: 0,
+    maxRunsPerCell: 0,
+    maxEdgesPerCell: 0,
+    maxTileEdges: 0,
+    truncatedCells: 0,
+    unfitTiles: 0,
+    insideRuns: 0,
+    excluded: 0,
+    immediate: 0,
+};
+/** The frame used when the anchor projection is unavailable */
+export const INACTIVE_ANCHOR_FRAME = {
+    terrain: null,
+    elevationQuery: null,
+    tileZoom: 0,
+    elevationScale: 0,
+    mainMatrix: null,
+    offsetUniforms: null,
+    useOffsetMode: false,
+    width: 0,
+    height: 0,
+    cameraMercator: null,
+};
+/**
+ * The terrain state of one draw instance.
+ *
+ * Treat it as an opaque handle: a custom renderer receives it as
+ * `CustomRendererDrawContext.terrain` and passes it to the renderers and to the terrain
+ * functions (such as {@link anchorElevationMeters} and {@link drawQuadSurfaceOnTerrain}).
+ * Constructing one gives a state with no terrain.
+ */
+export class TerrainContext {
+    constructor() {
+        /** This frame's terrain state (read by the shaders' projection uniforms) */
+        Object.defineProperty(this, "renderState", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: INACTIVE_TERRAIN_STATE
+        });
+        /**
+         * Suppression of adding elevation to vertices
+         *
+         * UI drawn as a rectangle on the screen (the rubber band of a box selection) stops being a
+         * rectangle once it is pasted onto the ground. The elevation is stopped only for such
+         * rendering.
+         *
+         * @internal
+         */
+        Object.defineProperty(this, "elevationSuppressed", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        /**
+         * Whether this is a frame that draws polygons and lines flat (the band where they cannot be
+         * made to follow the ground)
+         *
+         * In the zoomed-out band (z <= TERRAIN_ANALYTIC_MIN_ZOOM) the analytic drape is not used and
+         * polygons and lines are drawn by vertex displacement. In that band, however, the
+         * subdivision range (the DEM atlas intersected with the view) covers only a tiny part of the
+         * screen. Triangles outside the range are emitted without being subdivided, so only their
+         * vertices pick up an elevation while their interior pierces the mountain, and in a pitched
+         * view this becomes a vertical curtain (a cliff). The baked shape is not rebuilt until the
+         * camera stops, so during a zoom gesture the shape of an even older range is drawn.
+         *
+         * Over a wide area the relief amounts to only a dozen or so pixels on screen (the same
+         * reason the depth test is turned off). So polygons and lines are drawn without adding an
+         * elevation. The picture simply becomes the same as with the terrain off, and the cliff
+         * disappears by construction.
+         *
+         * Points, handles and symbols are out of scope. A symbol decided by a single vertex does not
+         * interpolate anything in between and so creates no cliff, and stopping its elevation would
+         * make it disagree with hit testing (the anchor projection).
+         *
+         * @internal
+         */
+        Object.defineProperty(this, "surfacesFlattened", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        /**
+         * The IDs of the datasets whose polygons and lines the analytic drape paints in this
+         * frame
+         *
+         * The decision "was it handed over to the drape" (whether to pile polygons and lines into
+         * the retained batch) is switched only after it has settled for several frames, to avoid
+         * flapping. That creates a window of several frames in which "the drape is already painting
+         * but the hand-over decision has not come back yet". If the immediate path draws the
+         * selection highlight during that window, everything outside the subdivision range becomes a
+         * flat slab floating above the terrain. Which way the highlight is drawn is therefore
+         * decided not by the decision but by whether it is actually being painted right now.
+         *
+         * @internal
+         */
+        Object.defineProperty(this, "drapePaintedDatasets", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        /**
+         * The light source of this frame's shading (null in a frame with no terrain)
+         *
+         * Read by the polygon fill of the vertex displacement path (`shaders/projection.ts` writes
+         * it into the uniforms). The analytic drape carries the light source in its own draw
+         * instructions, so this exists only to "deliver the same light to the other path as well".
+         * The light changes with the bearing, so it is set again every frame.
+         *
+         * @internal
+         */
+        Object.defineProperty(this, "shadeLight", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        /**
+         * The diagnostic values of the analytic drape
+         *
+         * @internal
+         */
+        Object.defineProperty(this, "drapeDebug", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: INITIAL_DRAPE_DEBUG
+        });
+        /**
+         * The entry point of this frame's quad analytic drape (null when the terrain is disabled)
+         *
+         * Images and the fill of text quads are drawn by QuadShader. CustomLayer puts it here
+         * every frame and QuadShader reads it and enters the path that "pastes it as ground pixels".
+         * It is always reset to null at the end of the frame, so it is never read from outside
+         * rendering.
+         *
+         * @internal
+         */
+        Object.defineProperty(this, "quadDrapeFrame", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        /**
+         * The subdivision grid spacing of the previous frame (Mercator). 0 means no terrain
+         *
+         * Used to decide whether to advance the generation. It is a per-instance value.
+         *
+         * This must not be looked at in meters. The conversion of the step into meters involves the
+         * latitude (`stepGrid * circumferenceAtLatitude(centerLat)`), so the value changes even when
+         * a pan moves the latitude by a single millidegree, and the generation advances every frame.
+         * Retained batches re-bake on a change of generation, so this amounts to "re-baking
+         * everything on every pan" (measured, frames during a pan reached 90 to 120 milliseconds).
+         * The grid spacing is a power of 2 in Mercator, so it changes only when a zoom level is
+         * crossed.
+         *
+         * @internal
+         */
+        Object.defineProperty(this, "stepGrid", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        /**
+         * The generation of the subdivision (a serial number closed within this instance)
+         *
+         * @internal
+         */
+        Object.defineProperty(this, "generation", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        /**
+         * The coarseness of the step actually used in this generation (1 = the terrain mesh nodes
+         * themselves)
+         *
+         * When a batch is subdivided coarsely for budget reasons, the chords of the coarse triangles
+         * dive under the hills of the terrain. The amount they dive grows in proportion to the step,
+         * so the depth bias is increased in proportion as well (gl.polygonOffset in view/layer/gl-state.ts).
+         * The renderer reports it on every build, and it is returned to 1 when the generation
+         * changes.
+         *
+         * @internal
+         */
+        Object.defineProperty(this, "tessellationCoarsening", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 1
+        });
+        /**
+         * The most recently decided subdivision range (Mercator)
+         *
+         * It is not recomputed while the atlas stays inside this rectangle. Recomputing it every
+         * frame to match the atlas would cause retained batches to be re-baked on every pan.
+         *
+         * @internal
+         */
+        Object.defineProperty(this, "tessellationRegion", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        /**
+         * The most recently built index of tile steps (recomputed at the same time as the range)
+         *
+         * @internal
+         */
+        Object.defineProperty(this, "tessellationTiling", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        /**
+         * The frame of the anchor projection
+         *
+         * @internal
+         */
+        Object.defineProperty(this, "anchorFrame", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: INACTIVE_ANCHOR_FRAME
+        });
+        /**
+         * The elevation cache within a single frame
+         *
+         * Hit testing calls project on the same vertex many times (hit testing, thinning, bbox). It
+         * costs about 3.5us per point, so it is worth reusing within a frame. It is thrown away
+         * every frame because the value may change once the DEM arrives in a new frame.
+         *
+         * @internal
+         */
+        Object.defineProperty(this, "elevationCache", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        /**
+         * The generation of the DEM coverage
+         *
+         * When the set of DEM tiles being drawn changes (a tile arrives, or the zoom changes), the
+         * already baked elevations become stale. Retained batches fetch the elevations again on a
+         * change of this value.
+         *
+         * @internal
+         */
+        Object.defineProperty(this, "elevationGeneration", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        /**
+         * The terrain tiles maplibre drew in the most recent frame (where the anchors read the drawn
+         * surface, `ground.ts`)
+         *
+         * @internal
+         */
+        Object.defineProperty(this, "coverage", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new TerrainCoverage()
+        });
+        /**
+         * Whether the camera is in motion (custom-layer writes it every frame)
+         *
+         * While it is moving, re-baking of retained batches is deferred. Re-baking during a gesture
+         * makes that one frame take several hundred milliseconds and the gesture catch, and it would
+         * have to be redone once the motion ends anyway.
+         *
+         * @internal
+         */
+        Object.defineProperty(this, "cameraMoving", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        /**
+         * The cache of occlusion tests within a single frame
+         *
+         * The same anchor is looked up many times in one frame (rendering and collision testing).
+         * The result changes once the camera moves, so it is thrown away every frame just like the
+         * elevation cache.
+         *
+         * @internal
+         */
+        Object.defineProperty(this, "occlusionCache", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+        /**
+         * The Mercator cells the globe asks the geometry to be cut into in this frame (null on a
+         * flat map)
+         *
+         * The context carries it because it is what every renderer of the instance holds: the cut
+         * of the globe goes through the same subdivision as the terrain (`view/globe-subdivision.ts`
+         * gives the step to the renderers when the terrain gives none).
+         *
+         * @internal
+         */
+        Object.defineProperty(this, "globeGrids", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        /**
+         * The generation of the globe cells (a serial number closed within this instance)
+         *
+         * It advances when the globe starts or stops being drawn and when a cell changes size, so
+         * the retained batches that baked the old cut are rebuilt.
+         *
+         * @internal
+         */
+        Object.defineProperty(this, "globeGeneration", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 0
+        });
+        /**
+         * The subdivision cache of polygon fills
+         *
+         * It depends on the generation and the step, so it is held per instance. Sharing it by
+         * feature id would pick up triangles subdivided with another instance's step.
+         *
+         * @internal
+         */
+        Object.defineProperty(this, "fillCache", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new TerrainFillCache()
+        });
+    }
+    /**
+     * The identifier of the DEM tile set seen most recently
+     *
+     * @internal
+     */
+    get coverageKey() {
+        return this.coverage.key;
+    }
+    /**
+     * Returns the state to its initial values (when the layer is destroyed)
+     *
+     * @internal
+     */
+    reset() {
+        this.renderState = INACTIVE_TERRAIN_STATE;
+        this.elevationSuppressed = false;
+        this.shadeLight = null;
+        this.drapeDebug = INITIAL_DRAPE_DEBUG;
+        this.stepGrid = 0;
+        this.tessellationRegion = null;
+        this.tessellationTiling = null;
+        this.tessellationCoarsening = 1;
+        this.anchorFrame = INACTIVE_ANCHOR_FRAME;
+        this.elevationCache = new Map();
+        this.occlusionCache = new Map();
+        this.coverage.clear();
+        this.fillCache.clear();
+        this.globeGrids = null;
+    }
+}
+/**
+ * Releases an instance's terrain state (when the layer is destroyed)
+ */
+export function releaseTerrainContext(context) {
+    context.reset();
+}

package/dist/view/terrain/dem-atlas.d.ts

@@ -0,0 +1,97 @@
+import { type RenderableTerrainTile, type TerrainLike } from './detect.js';
+/** The result of building the atlas */
+export interface DemAtlasResult {
+    texture: WebGLTexture;
+    /** [x0, y0, 1/width, 1/height] (Mercator) */
+    rect: [number, number, number, number];
+    /** [width, height] (texels) */
+    size: [number, number];
+    /** The maximum zoom of the tiles being drawn (used for the lift and the subdivision step) */
+    maxTileZoom: number;
+    /** The number of pixels within a tile, used to derive the ground size of one DEM pixel */
+    demDim: number;
+}
+/**
+ * The DEM atlas
+ */
+export declare class DemAtlas {
+    private gl;
+    private program;
+    private vao;
+    private quadBuffer;
+    private framebuffer;
+    private texture;
+    private textureWidth;
+    private textureHeight;
+    private destLoc;
+    private extentLoc;
+    private terrainLoc;
+    private matrixLoc;
+    private dimLoc;
+    private unpackLoc;
+    private exaggerationLoc;
+    /** What the atlas holds now, for skipping a bake that would give the same texels */
+    private bakedKey;
+    private bakedResult;
+    /** A number per DEM texture object (the key compares textures by identity) */
+    private textureIds;
+    private nextTextureId;
+    /** The number of bakes done (diagnostics and tests) */
+    bakeCount: number;
+    constructor(gl: WebGL2RenderingContext);
+    /**
+     * Bakes the DEM tiles being drawn into the atlas
+     *
+     * @param centerMercatorX The Mercator x of the camera center. Each tile is placed on the copy
+     *   of the world nearest to it, so the tiles on both sides of the antimeridian sit next to
+     *   each other (see `computeAtlasLayout`)
+     * @param tilesLoaded Whether every tile of the map has arrived (`map.areTilesLoaded()`).
+     *   While they have not, the DEM textures can be rewritten in place, so the atlas is baked
+     *   again on every frame; once they have, an unchanged frame reuses the last bake
+     * @returns null when it cannot be baked (the terrain is disabled, there is not a single
+     *   tile, or a GL resource could not be allocated)
+     */
+    build(terrain: TerrainLike, centerMercatorX?: number, tilesLoaded?: boolean): DemAtlasResult | null;
+    /**
+     * The key of everything a bake reads (two bakes with the same key give the same texels, as
+     * long as no DEM texture was rewritten in place)
+     */
+    private bakeKey;
+    /**
+     * Releases the GL resources
+     */
+    dispose(): void;
+    /**
+     * Compiles the baking program once (false when it cannot be created)
+     */
+    ensureProgram(): boolean;
+    private ensureTarget;
+}
+/** The layout of the atlas */
+export interface AtlasLayout {
+    minX: number;
+    minY: number;
+    spanX: number;
+    spanY: number;
+    width: number;
+    height: number;
+    maxZoom: number;
+}
+/**
+ * The Mercator x of the west edge of a tile, on the copy of the world nearest to the camera
+ *
+ * The tiles carry canonical x (0 to 2^z - 1). Across the antimeridian the view holds tiles from
+ * both ends of that range, and with canonical x their union would be the whole width of the
+ * world, crushing the resolution of the atlas. The tile is moved by whole turns (1 in Mercator
+ * units) so that its center is within half a turn of the camera center. This is the same
+ * placement maplibre gives the wrapped copies it draws.
+ */
+export declare function tileMercatorX(tile: RenderableTerrainTile, centerMercatorX: number): number;
+/**
+ * Decides the layout of the atlas from the tiles being drawn
+ *
+ * The range covered is the union of the Mercator rectangles of the tiles (each placed on the
+ * copy nearest to the camera, `tileMercatorX`), and the resolution aims at "assigning
+ * ATLAS_CELL_TEXELS to the finest tile", lowered only when it would exceed the upper bound.
+ */
+export declare function computeAtlasLayout(tiles: RenderableTerrainTile[], centerMercatorX: number): AtlasLayout | null;