@sakuzu/maplibre-gl-draw 1.0.0

package/dist/view/shaders/quad-grid.js

@@ -0,0 +1,128 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Subdivision of a textured quad (the degraded path)
+ *
+ * On frames where the analytic drape (`terrain/drape/quad.ts`) cannot be used,
+ * the quad is split to a fineness close to the grid of the terrain mesh. The
+ * resulting vertices are lifted by the shared GLSL
+ * (`terrain_elevation_from_offset` in `OFFSET_MODE_GLSL`), which looks up the
+ * elevation from the DEM atlas, so unlike a billboard with only four corners
+ * the terrain never pokes through from the inside.
+ *
+ * The step is aimed at half the node spacing of the terrain mesh. In theory,
+ * splitting to match the nodes themselves would be best, but a quad is a
+ * rotated rectangle, so cutting it along the grid produces trapezoids. With a
+ * half step, the amount by which a chord dips below the terrain inside a cell
+ * drops to about 1/4 of the node-aligned case and falls within the depth bias
+ * (`TERRAIN_DEPTH_BIAS`) applied to the whole frame.
+ *
+ * There is an upper limit on the total number of cells. This is so that the
+ * cost does not diverge even for a huge quad that covers a whole country;
+ * when the limit is hit, the caller reports the coarsening factor via
+ * `reportTerrainCoarsening` and the depth bias grows by the same amount (it
+ * rides directly on the same mechanism as the subdivision of polygons and
+ * lines).
+ */
+/** The maximum number of divisions per side */
+export const QUAD_GRID_MAX_DIVISIONS = 128;
+/** The upper limit on the total number of cells */
+export const QUAD_GRID_MAX_CELLS = 16384;
+/** The target step relative to the terrain mesh node spacing (half the fineness) */
+const QUAD_GRID_STEP_RATIO = 0.5;
+/**
+ * Decides the number of divisions
+ *
+ * @param quad The four corners in Mercator coordinates (x, y in the order top-left, top-right,
+ *   bottom-right, bottom-left)
+ * @param stepGrid The node spacing of the terrain mesh (Mercator). No subdivision if 0 or less
+ * @param stepRatio The target step relative to `stepGrid` (half of it on terrain; the globe
+ *   passes 1 to cut at its cell, `view/globe-subdivision.ts`)
+ */
+export function computeQuadGridSize(quad, stepGrid, stepRatio = QUAD_GRID_STEP_RATIO) {
+    if (!(stepGrid > 0))
+        return { nx: 1, ny: 1, coarsening: 1 };
+    const lengthU = Math.max(edgeLength(quad, 0, 1), edgeLength(quad, 3, 2));
+    const lengthV = Math.max(edgeLength(quad, 0, 3), edgeLength(quad, 1, 2));
+    const target = stepGrid * stepRatio;
+    let nx = clampDivisions(Math.ceil(lengthU / target));
+    let ny = clampDivisions(Math.ceil(lengthV / target));
+    if (nx * ny > QUAD_GRID_MAX_CELLS) {
+        const scale = Math.sqrt(QUAD_GRID_MAX_CELLS / (nx * ny));
+        nx = Math.max(1, Math.floor(nx * scale));
+        ny = Math.max(1, Math.floor(ny * scale));
+    }
+    const coarsening = Math.max(1, lengthU / nx / stepGrid, lengthV / ny / stepGrid);
+    return { nx, ny, coarsening };
+}
+/**
+ * Builds a grid by subdividing the four corners
+ *
+ * The interpolation is done on the Mercator plane. The interpolation of the
+ * texture coordinates when the GPU draws the four-corner billboard is also
+ * linear on the Mercator plane, so the appearance does not change when
+ * subdivided (interpolating on the lng/lat plane would introduce a slight
+ * stretch in the latitude direction).
+ *
+ * @param quad The four corners in Mercator coordinates (x, y in the order top-left, top-right,
+ *   bottom-right, bottom-left)
+ */
+export function buildQuadGrid(quad, nx, ny) {
+    const cols = nx + 1;
+    const rows = ny + 1;
+    const vertexCount = cols * rows;
+    const lngLat = new Float64Array(vertexCount * 2);
+    const texCoords = new Float32Array(vertexCount * 2);
+    for (let j = 0; j < rows; j++) {
+        const v = j / ny;
+        for (let i = 0; i < cols; i++) {
+            const u = i / nx;
+            // Bilinear interpolation (a = top-left, b = top-right, c = bottom-right, d = bottom-left)
+            const wa = (1 - u) * (1 - v);
+            const wb = u * (1 - v);
+            const wc = u * v;
+            const wd = (1 - u) * v;
+            const x = wa * quad[0] + wb * quad[2] + wc * quad[4] + wd * quad[6];
+            const y = wa * quad[1] + wb * quad[3] + wc * quad[5] + wd * quad[7];
+            const at = (j * cols + i) * 2;
+            lngLat[at] = x * 360 - 180;
+            lngLat[at + 1] = latFromMercatorY(y);
+            texCoords[at] = u;
+            texCoords[at + 1] = v;
+        }
+    }
+    const indices = new Uint16Array(nx * ny * 6);
+    let k = 0;
+    for (let j = 0; j < ny; j++) {
+        for (let i = 0; i < nx; i++) {
+            const topLeft = j * cols + i;
+            const topRight = topLeft + 1;
+            const bottomLeft = topLeft + cols;
+            const bottomRight = bottomLeft + 1;
+            indices[k++] = topLeft;
+            indices[k++] = bottomLeft;
+            indices[k++] = bottomRight;
+            indices[k++] = topLeft;
+            indices[k++] = bottomRight;
+            indices[k++] = topRight;
+        }
+    }
+    return { lngLat, texCoords, indices, vertexCount };
+}
+/** Mercator y -> latitude */
+function latFromMercatorY(y) {
+    const n = Math.PI - 2 * Math.PI * y;
+    return (180 / Math.PI) * Math.atan(0.5 * (Math.exp(n) - Math.exp(-n)));
+}
+/** The distance between two of the four corners (Mercator) */
+function edgeLength(quad, from, to) {
+    const dx = quad[to * 2] - quad[from * 2];
+    const dy = quad[to * 2 + 1] - quad[from * 2 + 1];
+    return Math.hypot(dx, dy);
+}
+/** Clamps the number of divisions into 1..the upper limit */
+function clampDivisions(value) {
+    if (!Number.isFinite(value) || value < 1)
+        return 1;
+    return Math.min(QUAD_GRID_MAX_DIVISIONS, Math.round(value));
+}

package/dist/view/shaders/quad.d.ts

@@ -0,0 +1,189 @@
+/**
+ * QuadShader
+ *
+ * A shader for drawing a textured quad (a quadrilateral).
+ * Uses MapLibre's projectTile to support pitch/roll/globe.
+ * Avoids coordinate precision problems with offset mode.
+ *
+ * On frames where terrain (3D) is enabled, a billboard with only four corners
+ * lets the terrain poke through from the inside, so the drawing is split into
+ * three ways.
+ *
+ * 1. Analytic drape (the preferred one). `terrain/drape/quad.ts` paints it as
+ *    pixels of the ground surface. Burying and clipping cannot occur by
+ *    construction, and behind a ridge it is hidden by the depth of the terrain
+ *    mesh
+ * 2. Subdivision (degraded). On frames where the resources for the analytic
+ *    drape cannot be prepared, the quad is split to the fineness of the
+ *    terrain mesh grid and an elevation is given per vertex
+ * 3. Four corner vertices (no terrain). This path is exactly identical to
+ *    before on a flat map. On the globe the same grid as 2 is cut along the
+ *    Mercator plane with the cell of the fills instead (no elevation), so the
+ *    quad follows the sphere the way maplibre's layers do
+ */
+import type { ProjectionData } from 'maplibre-gl';
+import type { TerrainContext } from '../terrain/context.js';
+import type { DrapeQuadCorners, QuadDrapeSurface } from '../terrain/drape/quad.js';
+import type { OffsetUniforms } from './helpers.js';
+/**
+ * The four corners of a quad, each `[lng, lat]` in degrees, as {@link computeQuadVertices}
+ * returns them.
+ */
+export interface QuadVertices {
+    /** The top-left corner (texture coordinate (0, 0)) */
+    topLeft: [number, number];
+    /** The top-right corner (texture coordinate (1, 0)) */
+    topRight: [number, number];
+    /** The bottom-left corner (texture coordinate (0, 1)) */
+    bottomLeft: [number, number];
+    /** The bottom-right corner (texture coordinate (1, 1)) */
+    bottomRight: [number, number];
+}
+/**
+ * Draws a textured quad on the map, such as a picture pasted onto it, following pitch,
+ * globe and terrain.
+ *
+ * Call `ensureShader` with the shader data of the frame and `setOffsetUniforms` before
+ * `draw`. On terrain the quad is painted as ground pixels when possible, otherwise it is
+ * subdivided to the terrain mesh.
+ */
+export declare class QuadShader {
+    private gl;
+    private program;
+    private variantName;
+    private vao;
+    private positionBuffer;
+    private texCoordBuffer;
+    private projectionUniformManager;
+    private textureLoc;
+    private opacityLoc;
+    private offsetUniforms;
+    private gridVao;
+    private gridPositionBuffer;
+    private gridTexCoordBuffer;
+    private gridIndexBuffer;
+    /** The most recently built grid (not rebuilt if the corners and divisions are the same) */
+    private grid;
+    private gridKey;
+    /** The vertex offsets of the grid (a work array re-subtracting the center every frame) */
+    private gridOffsets;
+    /** The capacity of the vertex buffer allocated on the GPU (number of elements) */
+    private gridPositionCapacity;
+    /**
+     * The terrain state of the draw instance being drawn (null draws without terrain)
+     *
+     * The CustomLayer passes its instance's context at construction. An extension renderer that
+     * owns a QuadShader calls `setTerrain(context.terrain)` with the draw context it receives.
+     */
+    private terrain;
+    constructor(gl: WebGL2RenderingContext, terrain?: TerrainContext | null);
+    /**
+     * Sets the terrain state the next draws use (null draws without terrain)
+     */
+    setTerrain(terrain: TerrainContext | null): void;
+    /**
+     * Initializes the buffers
+     */
+    private setupBuffers;
+    /**
+     * Sets the uniforms for offset mode
+     */
+    setOffsetUniforms(uniforms: OffsetUniforms): void;
+    /**
+     * Ensures the shader (recreating it when necessary)
+     */
+    ensureShader(shaderData: {
+        vertexShaderPrelude: string;
+        define: string;
+        variantName: string;
+    }): void;
+    /**
+     * Creates the shader program for a quad (offset mode)
+     */
+    private createQuadProgram;
+    /**
+     * Sets the projection uniforms (supporting offset mode + globe mode)
+     * @param projectionData MapLibre's ProjectionData
+     * @param zoom The current zoom level (used to switch offset mode)
+     */
+    private setProjectionUniforms;
+    /**
+     * Draws a quad
+     *
+     * @param vertices The four vertices of the quad (WGS84 coordinates [lng, lat])
+     * @param texture The texture
+     * @param opacity The opacity
+     * @param projectionData MapLibre's ProjectionData
+     * @param zoom The current zoom level
+     */
+    draw(vertices: QuadVertices, texture: WebGLTexture, opacity: number, projectionData: ProjectionData, zoom: number): void;
+    /**
+     * Draws with a subdivided grid (the degraded path)
+     *
+     * Splits the four corners to the fineness of the terrain mesh grid and adds
+     * the DEM elevation per vertex. Applying the elevation to the vertices is
+     * done by the shared GLSL, so the shader is the same one as the billboard.
+     *
+     * @returns true if it was drawn. When no subdivision is needed (the terrain
+     *   step is unavailable) it returns false and the caller draws with the
+     *   conventional four corner vertices
+     */
+    private drawSubdivided;
+    /**
+     * Draws with a grid cut along the Mercator plane on the globe
+     *
+     * @param cell The cell of the fills on the globe (Mercator; 0 on a flat map)
+     * @returns true if it was drawn. A flat map, and a quad inside one cell, return false and
+     *   the caller draws the four corners
+     */
+    private drawOnGlobe;
+    /**
+     * Draws the quad as a grid of `size` interpolated on the Mercator plane (shared by the
+     * terrain and the globe)
+     */
+    private drawGrid;
+    /**
+     * Uploads the texture coordinates and indices of the grid to the GPU
+     */
+    private uploadGridStatics;
+    /**
+     * Disposes of the resources
+     */
+    dispose(): void;
+}
+/**
+ * Paints a quad with a fill and text as pixels of the terrain surface.
+ *
+ * Used by custom renderers that draw text on a filled quad. The fill is decided by a
+ * rectangle fill and the text by an SDF atlas lookup, both within the same
+ * fragment, so a mismatch of subdivision between the fill and the text cannot
+ * occur.
+ *
+ * Returns false on frames with no terrain and on frames that have terrain but
+ * no entry point for the analytic drape (the DEM has not arrived, the shader
+ * cannot be built). The caller falls back to the conventional way of drawing
+ * (the fill texture + a separate draw of the text).
+ *
+ * @param terrain The terrain state of the draw instance being drawn
+ *   (`CustomRendererDrawContext.terrain`)
+ * @param corners The corners of the quad in degrees
+ * @param surface The fill and the text
+ * @param opacity The opacity, 0..1
+ * @returns true if it was painted; false when the caller must draw it another way
+ */
+export declare function drawQuadSurfaceOnTerrain(terrain: TerrainContext, corners: DrapeQuadCorners, surface: QuadDrapeSurface, opacity: number): boolean;
+/**
+ * Returns the corners of a rectangle of a size in degrees, rotated about its center.
+ *
+ * When a large image is placed at a low zoom level, the latitude may exceed
+ * +/-90 degrees. In that case it is scaled down automatically so that the
+ * whole thing is displayed.
+ *
+ * @param centerLng The center longitude
+ * @param centerLat The center latitude
+ * @param widthDeg The width (degrees)
+ * @param heightDeg The height (degrees)
+ * @param rotationRad The rotation angle (radians, counter-clockwise)
+ * @returns The four vertices of the quad (WGS84 coordinates [lng, lat])
+ */
+export declare function computeQuadVertices(centerLng: number, centerLat: number, widthDeg: number, heightDeg: number, rotationRad: number): QuadVertices;