@sakuzu/maplibre-gl-draw 1.0.0

package/dist/view/shaders/initializer.js

@@ -0,0 +1,125 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { calculateOffsetUniforms } from './helpers.js';
+/**
+ * ShaderInitializer
+ *
+ * Manages the shader initialization and the projection data setup of every
+ * renderer
+ *
+ * @internal
+ */
+export class ShaderInitializer {
+    constructor(renderers) {
+        Object.defineProperty(this, "renderers", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.renderers = renderers;
+    }
+    /**
+     * Makes every renderer ensure its shader
+     */
+    ensureShaders(shaderData) {
+        const { featureDrawer, tentativeRenderer, quadShader, strokeRenderer, pointShapeRenderer, pointInstanceRenderer, sdfLineRenderer, polygonBatchRenderer, sdfPolygonRenderer, } = this.renderers;
+        if (featureDrawer) {
+            featureDrawer.ensureShader(shaderData);
+        }
+        if (tentativeRenderer) {
+            tentativeRenderer.ensureShader(shaderData);
+        }
+        if (quadShader) {
+            quadShader.ensureShader(shaderData);
+        }
+        if (strokeRenderer) {
+            strokeRenderer.ensureShader(shaderData);
+        }
+        if (pointShapeRenderer) {
+            pointShapeRenderer.ensureShader(shaderData);
+        }
+        if (pointInstanceRenderer) {
+            pointInstanceRenderer.ensureShader(shaderData);
+        }
+        if (sdfLineRenderer) {
+            sdfLineRenderer.ensureShader(shaderData);
+        }
+        if (polygonBatchRenderer) {
+            polygonBatchRenderer.ensureShader(shaderData);
+        }
+        if (sdfPolygonRenderer) {
+            sdfPolygonRenderer.ensureShader(shaderData);
+        }
+    }
+    /**
+     * Sets the projection data on the renderers that need it
+     */
+    setProjectionData(projectionData) {
+        const { pointShapeRenderer, pointInstanceRenderer } = this.renderers;
+        if (pointShapeRenderer) {
+            pointShapeRenderer.setProjectionData(projectionData);
+        }
+        if (pointInstanceRenderer) {
+            pointInstanceRenderer.setProjectionData(projectionData);
+        }
+    }
+    /**
+     * Sets the uniforms for offset mode on every renderer
+     * Computes projectionCenter at 64-bit precision on the CPU side and passes it to each renderer
+     * The uniforms for globe mode are set directly from ProjectionData
+     */
+    setOffsetUniforms(centerLngLat, mainMatrix) {
+        this.applyOffsetUniforms(calculateOffsetUniforms(centerLngLat, mainMatrix));
+    }
+    /**
+     * Sets uniforms for offset mode that are already computed on every renderer
+     *
+     * The rendering of one copy of the world (the view across the antimeridian) computes its
+     * uniforms once per frame and applies them for each slot.
+     */
+    applyOffsetUniforms(uniforms) {
+        const { featureDrawer, tentativeRenderer, quadShader, strokeRenderer, pointShapeRenderer, pointInstanceRenderer, sdfLineRenderer, polygonBatchRenderer, sdfPolygonRenderer, } = this.renderers;
+        if (featureDrawer) {
+            featureDrawer.setOffsetUniforms(uniforms);
+        }
+        if (tentativeRenderer) {
+            tentativeRenderer.setOffsetUniforms(uniforms);
+        }
+        if (quadShader) {
+            quadShader.setOffsetUniforms(uniforms);
+        }
+        if (strokeRenderer) {
+            strokeRenderer.setOffsetUniforms(uniforms);
+        }
+        if (pointShapeRenderer) {
+            pointShapeRenderer.setOffsetUniforms(uniforms);
+        }
+        if (pointInstanceRenderer) {
+            pointInstanceRenderer.setOffsetUniforms(uniforms);
+        }
+        if (sdfLineRenderer) {
+            sdfLineRenderer.setOffsetUniforms(uniforms);
+        }
+        if (polygonBatchRenderer) {
+            polygonBatchRenderer.setOffsetUniforms(uniforms);
+        }
+        if (sdfPolygonRenderer) {
+            sdfPolygonRenderer.setOffsetUniforms(uniforms);
+        }
+    }
+    /**
+     * Increments the frame count of SDFLineRenderer
+     */
+    incrementSdfLineFrame() {
+        if (this.renderers.sdfLineRenderer) {
+            this.renderers.sdfLineRenderer.incrementFrame();
+        }
+    }
+}
+/**
+ * Creates a ShaderInitializer
+ */
+export function createShaderInitializer(renderers) {
+    return new ShaderInitializer(renderers);
+}

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

@@ -0,0 +1,123 @@
+/**
+ * ProjectionUniformManager
+ *
+ * A class that unifies the management of projection-related uniforms.
+ * It centralizes the uniform location lookup and setup that was duplicated in
+ * each renderer.
+ */
+import type { ProjectionData } from 'maplibre-gl';
+import type { TerrainContext } from '../terrain/context.js';
+import type { OffsetUniforms } from './helpers.js';
+/**
+ * The locations of the projection and terrain uniforms of one program, as
+ * {@link ProjectionUniformManager} looks them up. A location is null when the program does
+ * not declare the uniform.
+ */
+export interface ProjectionUniformLocations {
+    /** `u_projection_matrix`: the projection matrix of the frame */
+    matrix: WebGLUniformLocation | null;
+    /** `u_center_lnglat`: the view center in degrees, rounded to Float32 (offset mode) */
+    centerLngLat: WebGLUniformLocation | null;
+    /** `u_projection_center`: the view center in clip space (offset mode) */
+    projectionCenter: WebGLUniformLocation | null;
+    /** `u_units_per_degree`: Mercator units per degree at the center (offset mode) */
+    unitsPerDegree: WebGLUniformLocation | null;
+    /** `u_units_per_degree2`: the latitude correction of the above (offset mode) */
+    unitsPerDegree2: WebGLUniformLocation | null;
+    /** `u_use_offset_mode`: 1 to project relative to the center, 0 otherwise */
+    useOffsetMode: WebGLUniformLocation | null;
+    /**
+     * The gap between the reference coordinates of a retained batch and the linearization
+     * center (immediate mode uses [0, 0])
+     */
+    originShift: WebGLUniformLocation | null;
+    /** Globe: the Mercator coordinates of the tile (from maplibre's prelude) */
+    mercatorCoords: WebGLUniformLocation | null;
+    /** Globe: the clipping plane (from maplibre's prelude) */
+    clippingPlane: WebGLUniformLocation | null;
+    /** Globe: the transition between Mercator (0) and globe (1) */
+    transition: WebGLUniformLocation | null;
+    /** Globe: the fallback matrix (from maplibre's prelude) */
+    fallbackMatrix: WebGLUniformLocation | null;
+    /** Terrain: the Mercator coordinates of the view center */
+    centerMercator: WebGLUniformLocation | null;
+    /** Terrain: 1 while the terrain is drawn, 0 otherwise */
+    terrainOn: WebGLUniformLocation | null;
+    /** Terrain: the sampler of the DEM atlas */
+    demAtlas: WebGLUniformLocation | null;
+    /** Terrain: the Mercator rectangle the DEM atlas covers */
+    demAtlasRect: WebGLUniformLocation | null;
+    /** Terrain: the size of the DEM atlas */
+    demAtlasSize: WebGLUniformLocation | null;
+    /** Terrain: the parameters of the elevation lookup */
+    elevationParams: WebGLUniformLocation | null;
+    /** Terrain shading: the light direction (polygon fills only) */
+    lightDir: WebGLUniformLocation | null;
+    /** Terrain shading: the strength of the shading (polygon fills only) */
+    shadeStrength: WebGLUniformLocation | null;
+}
+/**
+ * Looks up and sets the projection and terrain uniforms of a program, for a custom renderer
+ * that uses {@link OFFSET_MODE_GLSL}.
+ *
+ * A class that manages the projection-related uniforms in one place
+ */
+export declare class ProjectionUniformManager {
+    private gl;
+    private locations;
+    private memo;
+    /**
+     * Whether this is a renderer that draws things stuck to the ground surface
+     * (polygons and lines)
+     *
+     * Only renderers with true stop applying the elevation on a frame that draws
+     * polygons and lines flat (the zoomed-out band; surfacesFlattened in
+     * `terrain/context.ts`). Symbols such as points, handles and text quads
+     * are determined by a single vertex and do not interpolate in between, so
+     * they do not create cliffs. Stopping the elevation would only put them out
+     * of step with hit testing (the anchor projection).
+     */
+    private readonly surface;
+    /**
+     * The terrain state of the draw instance being drawn (null draws without terrain)
+     *
+     * The renderers of a CustomLayer pass their instance's context at construction. A renderer
+     * of an extension implementation, which may be shared between draw instances, calls
+     * `setTerrain(context.terrain)` with the context it receives in each draw call.
+     */
+    private terrain;
+    constructor(gl: WebGL2RenderingContext, options?: {
+        surface?: boolean;
+        terrain?: TerrainContext | null;
+    });
+    /**
+     * Sets the terrain state the next uniforms are taken from (null draws without terrain)
+     */
+    setTerrain(terrain: TerrainContext | null): void;
+    /**
+     * Obtains the uniform locations from a program
+     *
+     * Rebuilding the program also resets the uniform values, so the record is
+     * discarded as well.
+     */
+    getLocations(program: WebGLProgram): ProjectionUniformLocations;
+    /**
+     * Obtains the current locations (getLocations() must be called first)
+     */
+    getCurrentLocations(): ProjectionUniformLocations | null;
+    /**
+     * Sets the projection uniforms
+     *
+     * A uniform whose value is the same as last time is not rewritten. Retained
+     * mode passes through here for every chunk, but the only thing that changes
+     * between chunks is u_origin_shift; the matrix and the camera-related values
+     * are invariant within a frame (see frame.ts).
+     *
+     * @param projectionData MapLibre's ProjectionData
+     * @param zoom The current zoom level
+     * @param offsetUniforms The uniforms for offset mode (null is allowed)
+     * @param originShift The gap between the reference coordinates of the vertex offsets and
+     *   the linearization center (the default is [0,0])
+     */
+    setUniforms(projectionData: ProjectionData, zoom: number, offsetUniforms: OffsetUniforms | null, originShift?: [number, number]): void;
+}

package/dist/view/shaders/projection.js

@@ -0,0 +1,299 @@
+// SPDX-FileCopyrightText: 2026 SAKAIDA Atsushi
+// SPDX-License-Identifier: AGPL-3.0-only
+import { INACTIVE_TERRAIN_STATE, TERRAIN_ATLAS_TEXTURE_UNIT, } from '../terrain/state.js';
+import { getRenderFrame } from './frame.js';
+/**
+ * Creates a record in the not-yet-written state
+ */
+function createMemo() {
+    return {
+        frame: -1,
+        mainMatrix: null,
+        globeSource: null,
+        useOffsetMode: Number.NaN,
+        originShiftX: Number.NaN,
+        originShiftY: Number.NaN,
+        centerSource: null,
+        offsetSource: null,
+        terrainSource: null,
+        terrainOn: Number.NaN,
+        terrainCenterSource: null,
+        shadeLight: null,
+        shadeStrength: Number.NaN,
+    };
+}
+/**
+ * Looks up and sets the projection and terrain uniforms of a program, for a custom renderer
+ * that uses {@link OFFSET_MODE_GLSL}.
+ *
+ * A class that manages the projection-related uniforms in one place
+ */
+export class ProjectionUniformManager {
+    constructor(gl, options = {}) {
+        Object.defineProperty(this, "gl", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "locations", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
+        Object.defineProperty(this, "memo", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: createMemo()
+        });
+        /**
+         * Whether this is a renderer that draws things stuck to the ground surface
+         * (polygons and lines)
+         *
+         * Only renderers with true stop applying the elevation on a frame that draws
+         * polygons and lines flat (the zoomed-out band; surfacesFlattened in
+         * `terrain/context.ts`). Symbols such as points, handles and text quads
+         * are determined by a single vertex and do not interpolate in between, so
+         * they do not create cliffs. Stopping the elevation would only put them out
+         * of step with hit testing (the anchor projection).
+         */
+        Object.defineProperty(this, "surface", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /**
+         * The terrain state of the draw instance being drawn (null draws without terrain)
+         *
+         * The renderers of a CustomLayer pass their instance's context at construction. A renderer
+         * of an extension implementation, which may be shared between draw instances, calls
+         * `setTerrain(context.terrain)` with the context it receives in each draw call.
+         */
+        Object.defineProperty(this, "terrain", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.gl = gl;
+        this.surface = options.surface === true;
+        this.terrain = options.terrain ?? null;
+    }
+    /**
+     * Sets the terrain state the next uniforms are taken from (null draws without terrain)
+     */
+    setTerrain(terrain) {
+        this.terrain = terrain;
+    }
+    /**
+     * Obtains the uniform locations from a program
+     *
+     * Rebuilding the program also resets the uniform values, so the record is
+     * discarded as well.
+     */
+    getLocations(program) {
+        const gl = this.gl;
+        this.memo = createMemo();
+        this.locations = {
+            // The basic projection
+            matrix: gl.getUniformLocation(program, 'u_projection_matrix'),
+            // For offset mode
+            centerLngLat: gl.getUniformLocation(program, 'u_center_lnglat'),
+            projectionCenter: gl.getUniformLocation(program, 'u_projection_center'),
+            unitsPerDegree: gl.getUniformLocation(program, 'u_units_per_degree'),
+            unitsPerDegree2: gl.getUniformLocation(program, 'u_units_per_degree2'),
+            useOffsetMode: gl.getUniformLocation(program, 'u_use_offset_mode'),
+            originShift: gl.getUniformLocation(program, 'u_origin_shift'),
+            // For globe mode
+            mercatorCoords: gl.getUniformLocation(program, 'u_projection_tile_mercator_coords'),
+            clippingPlane: gl.getUniformLocation(program, 'u_projection_clipping_plane'),
+            transition: gl.getUniformLocation(program, 'u_projection_transition'),
+            fallbackMatrix: gl.getUniformLocation(program, 'u_projection_fallback_matrix'),
+            // For terrain
+            centerMercator: gl.getUniformLocation(program, 'u_center_mercator'),
+            terrainOn: gl.getUniformLocation(program, 'u_terrain_on'),
+            demAtlas: gl.getUniformLocation(program, 'u_dem_atlas'),
+            demAtlasRect: gl.getUniformLocation(program, 'u_dem_atlas_rect'),
+            demAtlasSize: gl.getUniformLocation(program, 'u_dem_atlas_size'),
+            elevationParams: gl.getUniformLocation(program, 'u_elevation_params'),
+            // For terrain shading (null in shaders that do not declare them, and nothing is written)
+            lightDir: gl.getUniformLocation(program, 'u_light_dir'),
+            shadeStrength: gl.getUniformLocation(program, 'u_shade_strength'),
+        };
+        return this.locations;
+    }
+    /**
+     * Obtains the current locations (getLocations() must be called first)
+     */
+    getCurrentLocations() {
+        return this.locations;
+    }
+    /**
+     * Sets the projection uniforms
+     *
+     * A uniform whose value is the same as last time is not rewritten. Retained
+     * mode passes through here for every chunk, but the only thing that changes
+     * between chunks is u_origin_shift; the matrix and the camera-related values
+     * are invariant within a frame (see frame.ts).
+     *
+     * @param projectionData MapLibre's ProjectionData
+     * @param zoom The current zoom level
+     * @param offsetUniforms The uniforms for offset mode (null is allowed)
+     * @param originShift The gap between the reference coordinates of the vertex offsets and
+     *   the linearization center (the default is [0,0])
+     */
+    setUniforms(projectionData, zoom, offsetUniforms, originShift = [0, 0]) {
+        if (!this.locations)
+            return;
+        const gl = this.gl;
+        const locs = this.locations;
+        const memo = this.memo;
+        // Rewrite everything when the frame changes (insurance against a design where the
+        // contents change while the reference stays the same)
+        const frame = getRenderFrame();
+        const staleFrame = memo.frame !== frame;
+        // Use offset mode at high zoom levels (zoom >= 12)
+        const useOffsetMode = zoom >= 12 ? 1.0 : 0.0;
+        // Projection matrix
+        if (locs.matrix && (staleFrame || memo.mainMatrix !== projectionData.mainMatrix)) {
+            gl.uniformMatrix4fv(locs.matrix, false, projectionData.mainMatrix);
+            memo.mainMatrix = projectionData.mainMatrix;
+        }
+        // The offset mode flag
+        if (locs.useOffsetMode && (staleFrame || memo.useOffsetMode !== useOffsetMode)) {
+            gl.uniform1f(locs.useOffsetMode, useOffsetMode);
+            memo.useOffsetMode = useOffsetMode;
+        }
+        // The gap of the reference coordinates is always set (defaults to [0,0])
+        // This keeps a previous value from lingering when the same program is reused from a
+        // retained batch to immediate mode
+        // (only this one changes per chunk, so in practice it is written almost every time)
+        if (locs.originShift &&
+            (staleFrame || memo.originShiftX !== originShift[0] || memo.originShiftY !== originShift[1])) {
+            gl.uniform2f(locs.originShift, originShift[0], originShift[1]);
+            memo.originShiftX = originShift[0];
+            memo.originShiftY = originShift[1];
+        }
+        // centerLngLat is always set (because the relative coordinates are computed on the CPU
+        // side, it is required even at zoom < 12 so that the shader's fallback path can restore
+        // the absolute coordinates)
+        if (locs.centerLngLat && (staleFrame || memo.centerSource !== offsetUniforms)) {
+            if (offsetUniforms) {
+                gl.uniform2fv(locs.centerLngLat, offsetUniforms.centerLngLat);
+            }
+            else {
+                gl.uniform2fv(locs.centerLngLat, [0, 0]);
+            }
+            memo.centerSource = offsetUniforms;
+        }
+        // The uniforms specific to offset mode (used only when zoom >= 12)
+        // If the source is the same, the written values are the same too (null means the default
+        // values were written)
+        const offsetSource = offsetUniforms && useOffsetMode > 0 ? offsetUniforms : null;
+        if (staleFrame || memo.offsetSource !== offsetSource) {
+            if (offsetSource) {
+                if (locs.projectionCenter) {
+                    gl.uniform4fv(locs.projectionCenter, offsetSource.projectionCenter);
+                }
+                if (locs.unitsPerDegree) {
+                    gl.uniform3fv(locs.unitsPerDegree, offsetSource.unitsPerDegree);
+                }
+                if (locs.unitsPerDegree2) {
+                    gl.uniform3fv(locs.unitsPerDegree2, offsetSource.unitsPerDegree2);
+                }
+            }
+            else {
+                // Default values when not in offset mode
+                if (locs.projectionCenter) {
+                    gl.uniform4fv(locs.projectionCenter, [0, 0, 0, 0]);
+                }
+                if (locs.unitsPerDegree) {
+                    gl.uniform3fv(locs.unitsPerDegree, [1, 1, 1]);
+                }
+                if (locs.unitsPerDegree2) {
+                    gl.uniform3fv(locs.unitsPerDegree2, [0, 0, 0]);
+                }
+            }
+            memo.offsetSource = offsetSource;
+        }
+        // The uniforms for globe mode (taken from projectionData)
+        if (staleFrame || memo.globeSource !== projectionData) {
+            if (locs.mercatorCoords && projectionData.tileMercatorCoords) {
+                gl.uniform4fv(locs.mercatorCoords, projectionData.tileMercatorCoords);
+            }
+            if (locs.clippingPlane && projectionData.clippingPlane) {
+                gl.uniform4fv(locs.clippingPlane, projectionData.clippingPlane);
+            }
+            if (locs.transition) {
+                gl.uniform1f(locs.transition, projectionData.projectionTransition ?? 0);
+            }
+            if (locs.fallbackMatrix && projectionData.fallbackMatrix) {
+                gl.uniformMatrix4fv(locs.fallbackMatrix, false, projectionData.fallbackMatrix);
+            }
+            memo.globeSource = projectionData;
+        }
+        // The uniforms for terrain (taken from the frame state; when terrain is disabled,
+        // u_terrain_on = 0 makes the vertex computation exactly identical to before)
+        //
+        // The atlas origin is handed over as a value relative to the center Mercator
+        // coordinates. Sending absolute Mercator coordinates (values in 0-1 that use up the
+        // significant digits) as Float32 cannot express differences smaller than one atlas
+        // texel, which makes the elevation come out in steps.
+        const context = this.terrain;
+        const terrain = context?.renderState ?? INACTIVE_TERRAIN_STATE;
+        const suppressed = context?.elevationSuppressed === true;
+        const flattened = this.surface && context?.surfacesFlattened === true;
+        const terrainOn = terrain.active && !suppressed && !flattened ? 1 : 0;
+        if (staleFrame ||
+            memo.terrainSource !== terrain ||
+            memo.terrainOn !== terrainOn ||
+            memo.terrainCenterSource !== offsetUniforms) {
+            const centerMercX = offsetUniforms?.centerMercator[0] ?? 0;
+            const centerMercY = offsetUniforms?.centerMercator[1] ?? 0;
+            if (locs.terrainOn)
+                gl.uniform1f(locs.terrainOn, terrainOn);
+            if (locs.demAtlas)
+                gl.uniform1i(locs.demAtlas, TERRAIN_ATLAS_TEXTURE_UNIT);
+            if (locs.centerMercator)
+                gl.uniform2f(locs.centerMercator, centerMercX, centerMercY);
+            if (locs.demAtlasRect) {
+                gl.uniform4f(locs.demAtlasRect, terrain.atlasRect[0] - centerMercX, terrain.atlasRect[1] - centerMercY, terrain.atlasRect[2], terrain.atlasRect[3]);
+            }
+            if (locs.demAtlasSize) {
+                gl.uniform2f(locs.demAtlasSize, terrain.atlasSize[0], terrain.atlasSize[1]);
+            }
+            if (locs.elevationParams) {
+                gl.uniform2f(locs.elevationParams, terrain.elevationScale, terrain.liftMeters);
+            }
+            memo.terrainSource = terrain;
+            memo.terrainOn = terrainOn;
+            memo.terrainCenterSource = offsetUniforms;
+        }
+        // The uniforms of the terrain shading (declared only by the shaders of the polygon fill)
+        //
+        // The strength is set to 0 when there is no terrain and when drawing as a shape on the
+        // screen (things drawn with the elevation stopped, such as a rubber band). It is not set
+        // to 0 on a frame that draws polygons and lines flat (the zoomed-out band). Stopping the
+        // vertex displacement is a measure to avoid cliffs, and erasing the shading there as
+        // well would make the appearance of the fill jump at the boundary where the paths swap
+        // over (which is the very reason this shading was introduced).
+        if (locs.lightDir !== null || locs.shadeStrength !== null) {
+            const light = context?.shadeLight ?? null;
+            const shadeStrength = light !== null && terrain.active && !suppressed ? light.strength : 0;
+            if (staleFrame || memo.shadeLight !== light || memo.shadeStrength !== shadeStrength) {
+                if (locs.lightDir) {
+                    const d = light?.direction ?? [0, 0, 1];
+                    gl.uniform3fv(locs.lightDir, [d[0], d[1], d[2]]);
+                }
+                if (locs.shadeStrength)
+                    gl.uniform1f(locs.shadeStrength, shadeStrength);
+                memo.shadeLight = light;
+                memo.shadeStrength = shadeStrength;
+            }
+        }
+        memo.frame = frame;
+    }
+}

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

@@ -0,0 +1,77 @@
+/**
+ * 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 declare const QUAD_GRID_MAX_DIVISIONS = 128;
+/** The upper limit on the total number of cells */
+export declare const QUAD_GRID_MAX_CELLS = 16384;
+/** The number of divisions of the subdivision */
+export interface QuadGridSize {
+    /** The number of divisions in the u direction (top-left -> top-right) */
+    readonly nx: number;
+    /** The number of divisions in the v direction (top-left -> bottom-left) */
+    readonly ny: number;
+    /**
+     * The coarseness of the actual step relative to the terrain mesh node spacing
+     * (1 = same as the nodes)
+     */
+    readonly coarsening: number;
+}
+/**
+ * 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 declare function computeQuadGridSize(quad: ArrayLike<number>, stepGrid: number, stepRatio?: number): QuadGridSize;
+/**
+ * The subdivided grid (absolute coordinates; subtracting the per-frame center
+ * is done by the caller)
+ */
+export interface QuadGridGeometry {
+    /** The WGS84 coordinates of the vertices (a sequence of [lng, lat]; kept at 64-bit) */
+    readonly lngLat: Float64Array;
+    /** The texture coordinates of the vertices */
+    readonly texCoords: Float32Array;
+    /** The triangle indices */
+    readonly indices: Uint16Array;
+    /** The number of vertices */
+    readonly vertexCount: number;
+}
+/**
+ * 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 declare function buildQuadGrid(quad: ArrayLike<number>, nx: number, ny: number): QuadGridGeometry;