@sakuzu/maplibre-gl-draw 1.0.0

package/dist/view/terrain/drape/quad.d.ts

@@ -0,0 +1,249 @@
+/**
+ * Analytic drape for textured quads
+ *
+ * An Image (a picture pasted onto the map) and a quad with a fill and text are features that
+ * "fill the inside of a rectangle determined by four corners". Previously only
+ * those 4 vertices were drawn as a TRIANGLE_STRIP, so wherever the terrain rose
+ * above the plane spanned by the four corners it always cut through. The essence
+ * of the problem is the absence of subdivision, so turning off the depth test does
+ * not fix it (turning it off instead makes images behind a ridge show through).
+ *
+ * Here we solve it with the same idea as for polygons and lines. We draw a terrain
+ * mesh built by the same rules as MapLibre's, and for each pixel solve "is this
+ * ground point inside the quad" by inverse bilinear interpolation; if it is inside,
+ * the resulting (u, v) determines the content. Because it is painted as ground
+ * pixels, burying and dropouts cannot occur by construction, occlusion follows
+ * directly from the depth of the terrain mesh, and shading is applied with the same
+ * formula as the fill.
+ *
+ * There are two ways of deciding the content.
+ *
+ * - Image (`drawQuad`). The texture is looked up with (u, v)
+ * - Fill + text (`drawSurface`). The fill is a rectangle (color + border)
+ *   produced analytically, and the text looks up the glyph's occupancy rectangle
+ *   from (u, v) within the same per-pixel evaluation and references the SDF atlas.
+ *   Because the fill and the text become pixels of a single surface, no
+ *   subdivision mismatch between the two can occur, and since SDF is
+ *   resolution-independent the text stays crisp even on a huge quad
+ *
+ * Because quads are few in number, textures are bound one at a time in draw order
+ * (there is no need to pack styles into a texture as for polygons and lines).
+ */
+import type { ProjectionData } from 'maplibre-gl';
+import type { ShaderData } from '../../shaders/helpers.js';
+import type { RenderableTerrainTile, TerrainTileData } from '../detect.js';
+import { type DrapeLight } from './renderer.js';
+/** The four corners of a quad to drape on the terrain, each `[lng, lat]` in degrees. */
+export interface DrapeQuadCorners {
+    /** The corner at local (0, 0) */
+    readonly topLeft: readonly [number, number];
+    /** The corner at local (1, 0) */
+    readonly topRight: readonly [number, number];
+    /** The corner at local (0, 1) */
+    readonly bottomLeft: readonly [number, number];
+    /** The corner at local (1, 1) */
+    readonly bottomRight: readonly [number, number];
+}
+/** A color as RGBA, each 0..1, not premultiplied. */
+export type QuadDrapeColor = readonly [number, number, number, number];
+/**
+ * The fill of a draped quad: a background color and a border.
+ *
+ * Painted analytically instead of being baked into a Canvas. The border occupies
+ * "borderWidth inward", the same extent as Canvas's
+ * `strokeRect(bw/2, bw/2, w - bw, h - bw)`.
+ */
+export interface QuadDrapeFill {
+    /** Background color */
+    readonly color: QuadDrapeColor;
+    /** Border color */
+    readonly borderColor: QuadDrapeColor;
+    /** Border width (in the quad's local 0..1 coordinates. Separate for x and y) */
+    readonly border: readonly [number, number];
+}
+/**
+ * The text of a draped quad, as glyphs of an SDF atlas the caller owns.
+ *
+ * The glyph atlas owned by the caller is referenced as is. It is not
+ * held a second time here.
+ */
+export interface QuadDrapeGlyphs {
+    /** The texture of the SDF atlas */
+    readonly atlas: WebGLTexture;
+    /** Width of the atlas (texels) */
+    readonly atlasWidth: number;
+    /** Height of the atlas (texels) */
+    readonly atlasHeight: number;
+    /**
+     * Glyph array (8 elements per glyph)
+     *
+     * The occupancy rectangle (x0, y0, x1, y1) is in the quad's local 0..1
+     * coordinates, and the following 4 elements are the atlas UV (u0, v0, u1, v1).
+     */
+    readonly glyphs: Float32Array;
+    /** Number of glyphs */
+    readonly glyphCount: number;
+    /** Key telling whether repacking is needed (content, style, size, atlas version) */
+    readonly key: string;
+    /** Number of atlas texels per 1 unit of local coordinates (x, y) */
+    readonly atlasTexelsPerUnit: readonly [number, number];
+    /** Color of the letterform */
+    readonly color: QuadDrapeColor;
+    /** Color of the halo (outline) */
+    readonly haloColor: QuadDrapeColor;
+    /** Width of the halo (in units of the SDF value. 0 means no halo) */
+    readonly haloWidth: number;
+    /** Isosurface of the letterform (SDF value) */
+    readonly edge: number;
+    /** Change of the SDF value per atlas texel (= 1 / the radius of the distance field) */
+    readonly valuePerTexel: number;
+    /** Bias for mip selection (negative is toward the sharper side) */
+    readonly lodBias: number;
+}
+/** What {@link drawQuadSurfaceOnTerrain} paints inside a quad: a fill and optional text. */
+export interface QuadDrapeSurface {
+    /** The fill (background and border) */
+    readonly fill: QuadDrapeFill;
+    /** Text (null if there is none) */
+    readonly text: QuadDrapeGlyphs | null;
+}
+/**
+ * What is required in this frame to paste a quad onto the ground surface
+ *
+ * CustomLayer assembles it every frame and puts it into `terrain/state`, and
+ * QuadShader reads it when drawing. The per-tile DEM and ProjectionData are passed
+ * as "lookup functions". While the DEM of the target zoom has not arrived MapLibre
+ * returns the parent tile's texture and matrix, and replaces them the moment the
+ * real one arrives, so they must not be baked in (the polygon and line drape fell
+ * into the same trap).
+ */
+export interface QuadDrapeFrame {
+    /** Owner of the GPU resources (owned by CustomLayer) */
+    readonly renderer: QuadDrapeRenderer;
+    /** The shader variant for this frame */
+    readonly shaderData: ShaderData;
+    /** The terrain tiles to draw */
+    readonly tiles: readonly RenderableTerrainTile[];
+    /** The DEM of a single tile (null if it has not arrived) */
+    getTerrainData(tile: RenderableTerrainTile): TerrainTileData | null;
+    /** The ProjectionData of a single tile (null if it cannot be obtained) */
+    getProjectionData(tile: RenderableTerrainTile): ProjectionData | null;
+    /** Subdivision count of the terrain mesh */
+    readonly meshSize: number;
+    /** Light source of the shading (the same one as the polygon fill) */
+    readonly light: DrapeLight;
+    /**
+     * Whether to leave the depth test enabled after drawing has finished
+     *
+     * It changes partway through a frame (on through the layer drawing, off from the
+     * selection UI onward), so only this field is mutable.
+     */
+    keepDepthTest: boolean;
+}
+/**
+ * Converts the four corners into Mercator coordinates (in the order top left,
+ * top right, bottom right, bottom left)
+ *
+ * This order corresponds to (u, v) = (0,0), (1,0), (1,1), (0,1) of the inverse
+ * bilinear interpolation.
+ */
+export declare function quadMercatorCorners(corners: DrapeQuadCorners): Float64Array;
+/** The range of mesh rows to draw (rows that are not visible are not drawn) */
+export interface MeshRowRange {
+    readonly start: number;
+    readonly count: number;
+}
+/**
+ * A y range within a tile -> a range of terrain mesh rows
+ *
+ * The mesh indices are in row-major order, with the 6 * meshSize indices of row k
+ * laid out contiguously (the generation rule of `mesh.ts`). Simply dropping the
+ * rows the quad does not cover narrows the range while keeping a single
+ * drawElements call.
+ */
+export declare function meshRowRange(y0: number, y1: number, meshSize: number): MeshRowRange | null;
+/**
+ * Inverse bilinear interpolation on the CPU side (a mirror of the shader. For
+ * tests and diagnostics)
+ *
+ * @param quad The four corners (x, y in the order top left, top right, bottom
+ *   right, bottom left)
+ * @returns The (u, v) inside the quad. null if there is no solution
+ */
+export declare function solveQuadUV(px: number, py: number, quad: ArrayLike<number>): [number, number] | null;
+/**
+ * The renderer that pastes textured quads onto the ground surface
+ */
+export declare class QuadDrapeRenderer {
+    private gl;
+    private imageSlot;
+    private surfaceSlot;
+    private mesh;
+    private glyphCache;
+    /** A 1x1 texture bound to the samplers in frames that have no text */
+    private placeholderTex;
+    private useCounter;
+    /** The most recent failure reason (for diagnostics) */
+    lastError: string;
+    constructor(gl: WebGL2RenderingContext);
+    /**
+     * Allocates the terrain mesh
+     */
+    private ensureMesh;
+    /**
+     * Allocates a shader (one per fragment shader body)
+     */
+    private ensureProgram;
+    /**
+     * Allocates the shader and the mesh (the image path. Kept for existing callers)
+     */
+    ensure(shaderData: ShaderData, meshSize: number): boolean;
+    /**
+     * Allocates the shader and the mesh of the fill and text path
+     */
+    ensureSurface(shaderData: ShaderData, meshSize: number): boolean;
+    /**
+     * Pastes an image onto a single quad
+     *
+     * @returns true if it could be pasted (the caller then does not perform the
+     *   conventional flat drawing). false is returned only when the resources
+     *   cannot be prepared, in which case the caller falls back to the degraded
+     *   path.
+     */
+    drawQuad(corners: DrapeQuadCorners, texture: WebGLTexture, opacity: number, frame: QuadDrapeFrame): boolean;
+    /**
+     * Paints fill and text onto a single quad
+     *
+     * The fill is a rectangular fill, and the text looks up the SDF atlas within
+     * the same per-pixel evaluation.
+     *
+     * @returns true if it could be painted. false is returned only when the
+     *   resources cannot be prepared.
+     */
+    drawSurface(corners: DrapeQuadCorners, surface: QuadDrapeSurface, opacity: number, frame: QuadDrapeFrame): boolean;
+    /**
+     * Binds a 1x1 texture to the samplers when there is no text
+     *
+     * If drawing happens with a sampler left unbound and a texture of a different
+     * type remains on that unit, it is regarded as incomplete and the whole draw
+     * call is dropped. Even for pixels that do not read text, having something
+     * bound is safer.
+     */
+    private bindPlaceholderSamplers;
+    /**
+     * Draws the tiles the quad covers (the skeleton shared by image and fill)
+     */
+    private drawTiles;
+    /**
+     * Allocates the glyph data textures (no repacking if the key is the same)
+     */
+    private ensureGlyphBuffers;
+    /**
+     * Discards glyph data textures that are not in use (LRU)
+     */
+    private evictGlyphBuffers;
+    /**
+     * Releases the resources
+     */
+    dispose(): void;
+}