@sakuzu/maplibre-gl-draw 1.0.0

package/dist/view/terrain/state.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Accessors of the frame state of terrain rendering
+ *
+ * This is state during rendering that is set only while the terrain (MapLibre's terrain) is
+ * enabled. The owner of the values is the `TerrainContext` of each draw instance
+ * (`context.ts`; how a shared global broke with several instances is written there). Every
+ * accessor takes that context explicitly: the renderers of a CustomLayer receive their
+ * instance's context at construction, and extension renderers receive it in the draw context
+ * (`CustomRendererDrawContext.terrain`). Nothing here reads "the instance drawn last".
+ *
+ * When the terrain is disabled, `INACTIVE_TERRAIN_STATE` is held and the shader's
+ * `u_terrain_on` becomes 0. The vertex computation when it is 0 is exactly identical to
+ * the former one (this guarantees zero regression).
+ */
+import { INACTIVE_TERRAIN_STATE, type TerrainContext, type TerrainDrapeDebug, type TerrainRenderState } from './context.js';
+import type { QuadDrapeFrame } from './drape/quad.js';
+import type { TerrainShadeLight } from './shade.js';
+export type { TerrainDrapeDebug, TerrainRenderState };
+export { INACTIVE_TERRAIN_STATE };
+/**
+ * Replaces the terrain state of the frame (custom-layer calls this every frame)
+ */
+export declare function setTerrainRenderState(context: TerrainContext, state: TerrainRenderState): void;
+/**
+ * Whether giving elevation to the vertices is suppressed
+ *
+ * UI drawn as a rectangle on the screen (the rubber band of a rectangular selection) stops
+ * being a rectangle once it is pasted onto the ground surface. Elevation is stopped only
+ * for such drawing.
+ */
+export declare function isTerrainElevationSuppressed(context: TerrainContext): boolean;
+/**
+ * Whether this is a frame that draws polygons and lines flat (a band that cannot be made
+ * to follow the ground surface)
+ *
+ * The reason is written at `surfacesFlattened` in `context.ts`.
+ */
+export declare function isTerrainSurfacesFlattened(context: TerrainContext): boolean;
+/**
+ * Sets whether polygons and lines are drawn flat in this frame (custom-layer calls this
+ * every frame)
+ */
+export declare function setTerrainSurfacesFlattened(context: TerrainContext, flattened: boolean): void;
+/**
+ * Sets the shading light source of this frame (custom-layer calls this for each frame)
+ *
+ * null is set for frames where the terrain is disabled. While it is null, fills on the
+ * vertex displacement path are drawn with a shading factor of 1.0 (the same pixels as
+ * before the terrain was introduced).
+ */
+export declare function setTerrainShadeLight(context: TerrainContext, light: TerrainShadeLight | null): void;
+/**
+ * The shading light source of this frame (null when the terrain is disabled)
+ */
+export declare function getTerrainShadeLight(context: TerrainContext): TerrainShadeLight | null;
+/**
+ * Sets the datasets whose polygons and lines are painted by the analytic drape in this
+ * frame
+ *
+ * The reason is written at `drapePaintedDatasets` in `context.ts`.
+ */
+export declare function setDrapePaintedDatasets(context: TerrainContext, ids: ReadonlySet<string> | null): void;
+/**
+ * Whether the polygons and lines of this dataset are painted by the analytic drape in
+ * this frame
+ */
+export declare function isDrapePaintedDataset(context: TerrainContext, id: string): boolean;
+/**
+ * Whether the camera is in the middle of moving (used to decide to defer rebaking the
+ * retained batches)
+ */
+export declare function isTerrainCameraMoving(context: TerrainContext): boolean;
+/**
+ * Records the movement of the camera (custom-layer calls this every frame)
+ */
+export declare function setTerrainCameraMoving(context: TerrainContext, moving: boolean): void;
+/**
+ * Reports the coarseness of the step that was used (the polygon renderer calls this when
+ * building a batch)
+ *
+ * The coarsest value within the generation is kept. Only one depth bias can be set for the
+ * whole frame, so it is matched to a value at which the coarsest polygon does not sink.
+ */
+export declare function reportTerrainCoarsening(context: TerrainContext, factor: number): void;
+/**
+ * The coarsest step multiplier used in this generation
+ */
+export declare function getTerrainCoarsening(context: TerrainContext): number;
+/**
+ * Gets the handle of the quad analytic drape for this frame (null when the terrain is
+ * disabled)
+ *
+ * QuadShader (Image, and the fill of text quads) reads it.
+ */
+export declare function getQuadDrapeFrame(context: TerrainContext): QuadDrapeFrame | null;
+/** Sets the handle of the quad analytic drape (custom-layer calls this every frame) */
+export declare function setQuadDrapeFrame(context: TerrainContext, frame: QuadDrapeFrame | null): void;
+/** Sets the diagnostic values (custom-layer calls this) */
+export declare function setTerrainDrapeDebug(context: TerrainContext, value: TerrainDrapeDebug): void;

package/dist/view/terrain/state.js

@@ -0,0 +1,186 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Accessors of the frame state of terrain rendering
+ *
+ * This is state during rendering that is set only while the terrain (MapLibre's terrain) is
+ * enabled. The owner of the values is the `TerrainContext` of each draw instance
+ * (`context.ts`; how a shared global broke with several instances is written there). Every
+ * accessor takes that context explicitly: the renderers of a CustomLayer receive their
+ * instance's context at construction, and extension renderers receive it in the draw context
+ * (`CustomRendererDrawContext.terrain`). Nothing here reads "the instance drawn last".
+ *
+ * When the terrain is disabled, `INACTIVE_TERRAIN_STATE` is held and the shader's
+ * `u_terrain_on` becomes 0. The vertex computation when it is 0 is exactly identical to
+ * the former one (this guarantees zero regression).
+ */
+import { INACTIVE_TERRAIN_STATE, } from './context.js';
+export { INACTIVE_TERRAIN_STATE };
+/**
+ * Texture unit that binds the DEM atlas (unit 0 is used by the coordinate texture)
+ *
+ * @internal
+ */
+export const TERRAIN_ATLAS_TEXTURE_UNIT = 6;
+/**
+ * Gets the terrain state of the current frame
+ *
+ * @internal
+ */
+export function getTerrainRenderState(context) {
+    return context.renderState;
+}
+/**
+ * Replaces the terrain state of the frame (custom-layer calls this every frame)
+ */
+export function setTerrainRenderState(context, state) {
+    context.renderState = state;
+}
+/**
+ * Whether giving elevation to the vertices is suppressed
+ *
+ * UI drawn as a rectangle on the screen (the rubber band of a rectangular selection) stops
+ * being a rectangle once it is pasted onto the ground surface. Elevation is stopped only
+ * for such drawing.
+ */
+export function isTerrainElevationSuppressed(context) {
+    return context.elevationSuppressed;
+}
+/**
+ * Draws with the elevation turned off
+ *
+ * @internal
+ */
+export function withoutTerrainElevation(context, draw) {
+    const previous = context.elevationSuppressed;
+    context.elevationSuppressed = true;
+    try {
+        return draw();
+    }
+    finally {
+        context.elevationSuppressed = previous;
+    }
+}
+/**
+ * Whether this is a frame that draws polygons and lines flat (a band that cannot be made
+ * to follow the ground surface)
+ *
+ * The reason is written at `surfacesFlattened` in `context.ts`.
+ */
+export function isTerrainSurfacesFlattened(context) {
+    return context.surfacesFlattened;
+}
+/**
+ * Sets whether polygons and lines are drawn flat in this frame (custom-layer calls this
+ * every frame)
+ */
+export function setTerrainSurfacesFlattened(context, flattened) {
+    context.surfacesFlattened = flattened;
+}
+/**
+ * Sets the shading light source of this frame (custom-layer calls this for each frame)
+ *
+ * null is set for frames where the terrain is disabled. While it is null, fills on the
+ * vertex displacement path are drawn with a shading factor of 1.0 (the same pixels as
+ * before the terrain was introduced).
+ */
+export function setTerrainShadeLight(context, light) {
+    context.shadeLight = light;
+}
+/**
+ * The shading light source of this frame (null when the terrain is disabled)
+ */
+export function getTerrainShadeLight(context) {
+    return context.shadeLight;
+}
+/**
+ * Sets the datasets whose polygons and lines are painted by the analytic drape in this
+ * frame
+ *
+ * The reason is written at `drapePaintedDatasets` in `context.ts`.
+ */
+export function setDrapePaintedDatasets(context, ids) {
+    context.drapePaintedDatasets = ids;
+}
+/**
+ * Whether the polygons and lines of this dataset are painted by the analytic drape in
+ * this frame
+ */
+export function isDrapePaintedDataset(context, id) {
+    return context.drapePaintedDatasets?.has(id) === true;
+}
+/**
+ * Whether the vertex shader adds the elevation (the state combined with the suppression)
+ *
+ * @internal
+ */
+export function isTerrainElevationActive(context) {
+    return context.renderState.active && !context.elevationSuppressed;
+}
+/**
+ * Whether the subdivision on the CPU side is enabled
+ *
+ * This is independent of the suppression (`withoutTerrainElevation`), because subdivision
+ * is a matter of building the vertex data while suppression is a matter of drawing.
+ *
+ * @internal
+ */
+export function isTerrainTessellationActive(context) {
+    const state = context.renderState;
+    return state.active && state.stepMeters > 0;
+}
+/**
+ * Whether the camera is in the middle of moving (used to decide to defer rebaking the
+ * retained batches)
+ */
+export function isTerrainCameraMoving(context) {
+    return context.cameraMoving;
+}
+/**
+ * Records the movement of the camera (custom-layer calls this every frame)
+ */
+export function setTerrainCameraMoving(context, moving) {
+    context.cameraMoving = moving;
+}
+/**
+ * Reports the coarseness of the step that was used (the polygon renderer calls this when
+ * building a batch)
+ *
+ * The coarsest value within the generation is kept. Only one depth bias can be set for the
+ * whole frame, so it is matched to a value at which the coarsest polygon does not sink.
+ */
+export function reportTerrainCoarsening(context, factor) {
+    if (factor > context.tessellationCoarsening)
+        context.tessellationCoarsening = factor;
+}
+/**
+ * The coarsest step multiplier used in this generation
+ */
+export function getTerrainCoarsening(context) {
+    return context.tessellationCoarsening;
+}
+/**
+ * Gets the handle of the quad analytic drape for this frame (null when the terrain is
+ * disabled)
+ *
+ * QuadShader (Image, and the fill of text quads) reads it.
+ */
+export function getQuadDrapeFrame(context) {
+    return context.quadDrapeFrame;
+}
+/** Sets the handle of the quad analytic drape (custom-layer calls this every frame) */
+export function setQuadDrapeFrame(context, frame) {
+    context.quadDrapeFrame = frame;
+}
+/**
+ * Gets the diagnostic values
+ *
+ * @internal
+ */
+export function getTerrainDrapeDebug(context) {
+    return context.drapeDebug;
+}
+/** Sets the diagnostic values (custom-layer calls this) */
+export function setTerrainDrapeDebug(context, value) {
+    context.drapeDebug = value;
+}

package/dist/view/terrain/tessellation.d.ts

@@ -0,0 +1,265 @@
+/**
+ * Tessellation for terrain
+ *
+ * On terrain, a long segment sinks into the ground where it crosses a valley and floats
+ * above a ridge. Since elevation can only be given to vertices, the only option is to cut
+ * segments and triangles finely and give elevation to the split points as well.
+ *
+ * ## Why we align with "the lattice of MapLibre's terrain mesh"
+ *
+ * If the step were an arbitrary interval, we would be sampling the same DEM with "two
+ * triangulations that know nothing about each other". Neither the vertex positions nor the
+ * directions of the triangle diagonals would agree, so the two surfaces would never agree
+ * exactly anywhere, and the discrepancy is largest where the twist inside a DEM cell is
+ * largest -- at the creases of a slope. Making the tessellation finer only makes the
+ * discrepancy asymptotically smaller, never zero, and a constant lift cannot cover it.
+ *
+ * So we place the split points on the lattice nodes of MapLibre's terrain mesh themselves.
+ * MapLibre draws terrain on a regular lattice that divides one tile into `terrain.meshSize`
+ * (128 by default) parts, so the nodes line up at multiples of 1/(2^z * meshSize) in
+ * Mercator coordinates. On a node both elevations become the same interpolated value of the
+ * same DEM, so the surfaces agree. We also match the direction of the cell diagonal to
+ * MapLibre (getTerrainMesh splits along the main diagonal (x, y) -> (x+1, y+1)), so they
+ * agree inside a cell as well. All that remains is floating point rounding, and that can be
+ * covered with a depth bias.
+ *
+ * The lattice is defined in Mercator space, so the tessellation is done in Mercator space
+ * too. A lattice with equal intervals in longitude and latitude does not sit on the Mercator
+ * lattice (the latitude direction is non-linear). Input and output stay in longitude and
+ * latitude; only the internals move to Mercator.
+ *
+ * This code is only reached when terrain is enabled. When it is disabled the caller passes
+ * straight through, so the result is byte-for-byte identical to the conventional rendering.
+ */
+import type { Coordinate } from '../../store/types.js';
+/**
+ * A rectangle in Web Mercator coordinates (0..1 across the world, y growing southward).
+ */
+export interface MercatorRect {
+    /** The west edge */
+    readonly x0: number;
+    /** The north edge */
+    readonly y0: number;
+    /** The east edge */
+    readonly x1: number;
+    /** The south edge */
+    readonly y1: number;
+}
+/**
+ * How finely a line or a fill is subdivided to follow the terrain mesh, as
+ * {@link getTerrainTessellationStep} returns it.
+ */
+export interface TessellationStep {
+    /**
+     * Lattice interval (in Mercator units)
+     *
+     * The node interval of MapLibre's terrain mesh, 1/(2^z * meshSize), or that value
+     * coarsened by a power of two. Even when coarsened it still sits on a subset of the nodes.
+     */
+    readonly grid: number;
+    /** Upper limit on the number of vertices that may be generated */
+    readonly maxPoints: number;
+    /**
+     * The area that may be tessellated (in Mercator; null means no area = split anywhere)
+     *
+     * Elevation is read from the DEM atlas, but the atlas only covers the neighbourhood of
+     * the view, and outside it the value saturates at the edge value (`dem_elevation_meters`
+     * in `shaders/helpers.ts` clamps the uv). In other words, splitting finely outside the
+     * atlas only splits a flat surface finely while it stays flat, and the elevation does not
+     * change by a single metre.
+     *
+     * Splitting there anyway was the root of the slowness. With a dataset
+     * (8,172 administrative boundaries, all of Japan), the cost of splitting even the features
+     * that never appear on screen ate up the batch's tessellation budget, and the uniform
+     * coarsening applied to stay within the budget (up to 64x) reached even the features on
+     * screen. The chord of a coarse triangle dives below a hill, gets cut away by the depth
+     * test, and a hole opens in the fill.
+     *
+     * So we limit the area we split to the atlas (plus a margin). The cost is decided by how
+     * wide the view is and no longer depends on the number of records, so what is on screen
+     * can always be split at the finest step.
+     */
+    readonly region?: MercatorRect | null;
+    /**
+     * The actual mesh step of each terrain tile (if null, `grid` is used everywhere)
+     *
+     * MapLibre's terrain is drawn with a fixed lattice per tile, and in a pitched view the
+     * more distant the view is, the coarser the zoom of the tiles used. Matching the step to
+     * the tile's actual mesh makes our own surface agree with MapLibre's both on the nodes and
+     * inside the cells. If it is not matched, too fine a step sinks along the valley bottoms
+     * and too coarse a step dives under the ridges, and both are cut away by depth.
+     */
+    readonly tiling?: TessellationTiling | null;
+    /**
+     * The coarsening factor applied to the tile step (a power of two; 1 = the actual mesh)
+     *
+     * Splitting at the actual mesh itself is ideal, but in a wide view the amount to split
+     * jumps. As long as we coarsen by a power of two, the split points keep sitting on a
+     * subset of the actual mesh nodes, so the problem of sinking along the valley bottoms does
+     * not occur (sinking happens when we leave the nodes). What remains is only that the chord
+     * dives slightly under a ridge, and that can be covered with a depth bias proportional to
+     * the step. Keep the factor small (TERRAIN_MAX_TILED_COARSEN).
+     */
+    readonly coarsen?: number;
+}
+/**
+ * The subdivision step of each terrain tile, indexed by a grid of cells.
+ *
+ * The set of tiles is indexed by cells the size of the finest tile. A coarse tile spans
+ * several cells, but a cell boundary always lies on one of that tile's mesh lines (the side
+ * length of the finest tile is an integer multiple of the mesh interval), so cutting along
+ * the cells does not create a seam.
+ */
+export interface TessellationTiling {
+    /** The area the index covers (in Mercator) */
+    readonly rect: MercatorRect;
+    /** The side length of an index cell (= the side length of the finest tile) */
+    readonly cell: number;
+    /** The number of cell columns */
+    readonly cols: number;
+    /** The number of cell rows */
+    readonly rows: number;
+    /** The step of each cell (0 = there is no tile = do not split) */
+    readonly grids: Float64Array;
+}
+/**
+ * Whether the rectangles intersect
+ */
+export declare function rectsIntersect(minX: number, minY: number, maxX: number, maxY: number, region: MercatorRect): boolean;
+/**
+ * Whether the rectangle `outer` wholly contains the rectangle `inner`
+ */
+export declare function containsRect(outer: MercatorRect, inner: MercatorRect): boolean;
+/**
+ * Expand a rectangle outwards by `margin` as a ratio of its side lengths
+ */
+export declare function expandRect(rect: MercatorRect, margin: number): MercatorRect;
+/**
+ * The intersection of two rectangles (null if they do not intersect)
+ */
+export declare function intersectRect(a: MercatorRect, b: MercatorRect): MercatorRect | null;
+/**
+ * Convert the DEM atlas uniform representation [x0, y0, 1/width, 1/height] into a rectangle
+ */
+export declare function atlasCoverage(rect: readonly [number, number, number, number]): MercatorRect;
+/**
+ * The number of lattice cells a bounding box touches within the area (an estimate)
+ *
+ * We do not split outside the area, so it is left out of the cost estimate too.
+ */
+export declare function cellsInRegion(minX: number, minY: number, maxX: number, maxY: number, grid: number, region: MercatorRect | null | undefined): number;
+/** The result of the triangulation */
+export interface TessellatedFill {
+    flatCoords: number[];
+    indices: number[];
+    /**
+     * Whether the step was too fine to split through
+     *
+     * When true, the result contains triangles that are "left as they were (flat triangles
+     * that do not follow the terrain)". Either the vertex budget ran out, or one triangle
+     * covered too many cells. A flat triangle is visible as a wedge piercing the terrain, so
+     * the caller must coarsen the step and split again (tessellatePolygonFill in
+     * terrain/polygon.ts). It is exactly this mixture of "fine in places, flat in the rest"
+     * that is the real cause of the visual breakdown.
+     */
+    overflowed: boolean;
+    /**
+     * By what factor the step has to be coarsened to split through (1 = it split through as
+     * it was)
+     *
+     * Repeating "it did not split through, so double it and try again" means that for a huge
+     * feature (a municipal boundary with 130,000 vertices, for example) the work is redone
+     * every time up to the limit of 6 rounds, spending hundreds of milliseconds on a single
+     * feature. The factor we need follows directly from the amount that overflowed, so we
+     * return it and get it right in one go.
+     */
+    overflowFactor: number;
+}
+/** Longitude -> Mercator x */
+export declare function mercatorX(lng: number): number;
+/** Latitude -> Mercator y */
+export declare function mercatorY(lat: number): number;
+/** Mercator x -> longitude */
+export declare function lngFromMercatorX(x: number): number;
+/** Mercator y -> latitude */
+export declare function latFromMercatorY(y: number): number;
+/**
+ * Inserts vertices where a line crosses the lattice of the terrain mesh, so that it follows
+ * the terrain when each vertex is lifted.
+ *
+ * The original vertices are always kept, and only the intersections with the lattice lines
+ * are inserted. The intersections are found by linear interpolation in Mercator space
+ * (rendering also draws a straight line after projection, so an inserted point always lies
+ * on the original line).
+ *
+ * @param path The vertices `[lng, lat]` in degrees
+ * @param step The step from {@link getTerrainTessellationStep}
+ * @returns The densified vertices. The input itself for fewer than 2 positions or a step of
+ *   0; insertion stops when `step.maxPoints` is reached
+ */
+export declare function densifyPath(path: readonly Coordinate[], step: TessellationStep): Coordinate[];
+/**
+ * Emit a triangle with its winding order aligned
+ *
+ * The terrain-following fill culls the far side of a ridge with back-face culling (the cure
+ * for the silhouette bleed-through in which a fill laid on the far slope shows through the
+ * ridge in front). For the culling to hold, the winding order of every triangle must be
+ * uniform, but the orientation of the input ring (clockwise / counter-clockwise) differs
+ * from feature to feature. So here we normalise to the orientation in which the cross
+ * product in Mercator (x right, y down) is positive. In a y-down coordinate system a
+ * positive cross product = clockwise on screen = counter-clockwise in GL window coordinates
+ * (y up) = the front face of the default frontFace(CCW).
+ */
+export declare function pushOriented(out: number[], pool: VertexPool, a: number, b: number, c: number): void;
+/**
+ * The vertex pool (held in Mercator coordinates, with duplicates merged)
+ *
+ * By assigning the same number to the same coordinate, neighbouring triangles share their
+ * split points. If they are shared, their elevations necessarily agree too, so no crack
+ * appears in the fill.
+ *
+ * The longitude and latitude of the vertices that were there from the start are emitted as
+ * they are, without a round trip through the conversion.
+ */
+declare class VertexPool {
+    private readonly mx;
+    private readonly my;
+    private readonly lng;
+    private readonly lat;
+    /** A two-stage lookup, x -> (y -> number) (the keys are numbers; no strings are made) */
+    private readonly lookup;
+    private readonly limit;
+    private overflow;
+    constructor(source: readonly number[], maxPoints: number);
+    exhausted(): boolean;
+    /**
+     * How many times the budget's worth of vertices we tried to create (usable as a step
+     * factor)
+     *
+     * The vertex count is inversely proportional to the square of the step, so the square root
+     * gives the step factor.
+     */
+    overflowRatio(): number;
+    /**
+     * Register a Mercator coordinate and return its number
+     *
+     * The matching is exact. It is tempting to round before matching, but it must not be
+     * done. The intersection of a lattice line and an edge can come arbitrarily close to a
+     * lattice node, so with even the slightest rounding "a nearby but different point" is
+     * treated as the same one, that cell's fragment degenerates and drops out, and a hole one
+     * cell wide opens in the surface (measured). With exact matching, what remains instead is
+     * that vertices that are "the same point but differ in the last bit" occasionally survive.
+     * That becomes a crack 1e-16 degrees wide (1e-11 m on the ground), but it does not show on
+     * screen. Unlike a hole, the coverage of the surface is not lost.
+     *
+     * The key is a two-stage numeric lookup. A Map's numeric keys use SameValueZero
+     * comparison, so the matching is just as exact as it was back when we turned them into the
+     * string `${x},${y}`, while the per-point string creation disappears.
+     */
+    intern(x: number, y: number): number;
+    x(index: number): number;
+    y(index: number): number;
+    /** Build the flattened coordinate array of longitudes and latitudes */
+    output(): number[];
+}
+export {};