@sakuzu/maplibre-gl-draw 1.0.0

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

@@ -0,0 +1,184 @@
+/**
+ * Analytic drape rendering
+ *
+ * Instead of placing features onto the terrain as "a collection of triangles",
+ * they are painted as "pixels of the ground surface". A mesh built by the same
+ * rules as MapLibre's terrain mesh is drawn, and the fragment shader solves
+ * analytically whether that pixel is inside the feature and how far it is from the
+ * outline.
+ *
+ * With this, the "tears, streaks and holes" that stem from a mismatch in the
+ * subdivision of the surface cannot occur by construction (there is no room for
+ * our own triangles to disagree with the terrain). No lift (depth bias) is needed
+ * either, so the "silhouette show-through" in which the fill on the far side of a
+ * ridge shows through does not exist in principle. The line width can also be kept
+ * constant in screen pixels (the inverse Jacobian maps a distance in tile-local
+ * coordinates to a screen distance).
+ *
+ * The limits and the degradation follow the upper limits of binning.ts. Only when
+ * those limits are exceeded does the caller fall back to the conventional vertex
+ * displacement path.
+ */
+import type { ProjectionData } from 'maplibre-gl';
+import type { ShaderData } from '../../shaders/helpers.js';
+import type { TerrainTileData } from '../detect.js';
+import { type DrapePackBuilder } from './bin-store.js';
+import { EDGE_UNITS } from './edge-constrain.js';
+import type { ResolvedTileEdges } from './stitch.js';
+export { EDGE_UNITS };
+/**
+ * Upper limit on the sources of the factors
+ *
+ * 0 = neutral (factor 1), then the datasets, then the Store layers
+ * (their opacity; see `drapeLayerSource` in pass.ts). A dataset past the limit is
+ * drawn with a factor of 1 (the plain color), and a layer past it has its opacity
+ * baked into its colors. 64 vec2 stay well inside the 224 fragment uniform vectors
+ * WebGL2 guarantees.
+ */
+export declare const DRAPE_MAX_SOURCES = 64;
+/**
+ * The light source of the shading
+ *
+ * The default is "direction 335 degrees, anchor viewport", the same as hillshade.
+ * Light from the northwest is the standard practice in cartography, whereas light
+ * from the southeast causes the illusion that the relief is inverted. Neither a UI
+ * nor an option is provided; it is held as the default value of a uniform. Even if
+ * it is changed in the future, only the way the uniform is supplied needs to
+ * change.
+ */
+export interface DrapeLight {
+    /** A unit vector in the map coordinate system (east, north, up) */
+    readonly direction: readonly [number, number, number];
+    /** Strength of the shading (0 means no shading) */
+    readonly strength: number;
+}
+/**
+ * The defaults of the shading, 335 degrees as seen on screen (northwest), an
+ * altitude of 45 degrees and a strength of 0.45
+ */
+export declare const DRAPE_LIGHT_AZIMUTH_DEG = 335;
+export declare const DRAPE_LIGHT_ALTITUDE_DEG = 45;
+export declare const DRAPE_LIGHT_STRENGTH = 0.45;
+/**
+ * Converts a screen-anchored (anchor viewport) light source into a vector in the
+ * map coordinate system
+ *
+ * So that the light always comes from the top left on screen, the map's rotation
+ * (bearing) is added to convert it into an azimuth in the map coordinate system.
+ */
+export declare function resolveDrapeLight(bearingDeg: number): DrapeLight;
+/**
+ * A segment of range drawing
+ *
+ * Only [paintFrom, paintTo) of the element sequence is painted. It is used to
+ * insert an image (a quad) between polygons and lines following the stacking
+ * order. The selection highlight accumulates its coverage from every element, so
+ * emitSelection is raised only for the final segment and it is composed once.
+ */
+export interface DrapeDrawSegment {
+    readonly paintFrom: number;
+    readonly paintTo: number;
+    readonly emitSelection: boolean;
+}
+/** The drawing instruction for a single tile */
+export interface DrapeTileDraw {
+    /** The tile ID passed to getProjectionData */
+    readonly tileID: unknown;
+    /** The complete set of DEM textures */
+    readonly terrain: TerrainTileData;
+    /** The starting position within the cell index texture (texels) */
+    readonly cellOffset: number;
+    /** The subdivision count of the grid (per side) */
+    readonly grid: number;
+    /** The ground size of this tile (meters). Used to compute the shading gradient */
+    readonly groundMeters: number;
+    /**
+     * The constraint for each edge (resolving T-junctions)
+     *
+     * The step, the coordinate transform and the DEM of the constraint target come
+     * as a single value. This shape makes it impossible to create a state in which
+     * only one of them is stale.
+     */
+    readonly edges: ResolvedTileEdges<TerrainTileData>;
+}
+/**
+ * The ratio of the lift from the ground surface (a proportion of the tile's ground
+ * size)
+ *
+ * One ten-thousandth. That amounts to 2 m for a z11 tile (about 19 km) and 6 cm
+ * for z16 (about 600 m). On screen it is less than 0.1 pixel, so it is invisible,
+ * yet in depth it reliably wins against the terrain surface.
+ */
+export declare const DRAPE_LIFT_RATIO: number;
+/**
+ * The shader that paints the pixels (exported because a test watches its structure)
+ */
+export declare const DRAPE_FRAGMENT_SOURCE: string;
+/**
+ * The renderer of the analytic drape
+ */
+export declare class DrapeRenderer {
+    private gl;
+    private program;
+    private variantName;
+    private mesh;
+    private edgeTex;
+    private runTex;
+    private cellTex;
+    private styleTex;
+    private edgeTexSize;
+    private runTexSize;
+    private cellTexSize;
+    private styleTexSize;
+    private uploaded;
+    /** The selection version the transferred style table reflects (-1 = not transferred) */
+    private uploadedSelection;
+    private locations;
+    /** The most recent failure reason (for diagnostics) */
+    lastError: string;
+    /** MAX_TEXTURE_SIZE of the context (read once, 0 = not read yet) */
+    private maxTextureSize;
+    constructor(gl: WebGL2RenderingContext);
+    /**
+     * Allocates the shader and the mesh
+     */
+    ensure(shaderData: ShaderData, meshSize: number): boolean;
+    /**
+     * Transfers the part of the packed arrays that has not been sent yet to the GPU
+     *
+     * The arrays are append-only, so sending only the rows that were added is
+     * enough. Everything is sent only when the version has been swapped (it became a
+     * different builder) and when the textures have been recreated.
+     *
+     * @returns false when a table does not fit in a texture of this GPU (taller than
+     *   MAX_TEXTURE_SIZE, or the allocation failed). The caller then draws the frame
+     *   without the analytic drape, the same way as when the index is over its budget
+     */
+    upload(pack: DrapePackBuilder): boolean;
+    /**
+     * Draws a single tile
+     *
+     * @param projectionData The ProjectionData of that tile
+     * @param sourceFactors The factors per source (x = opacity, y = size)
+     * @param opacity The overall opacity (default 1)
+     * @param segment The segment of range drawing (omitted = all elements + the
+     *   selection highlight). When inserting an image between polygons and lines
+     *   following the stacking order, the caller splits the element sequence at the
+     *   image's position and draws it segment by segment
+     */
+    drawTile(draw: DrapeTileDraw, projectionData: ProjectionData, light: DrapeLight, zoom: number, sourceFactors: Float32Array, pixelRatio?: number, opacity?: number, segment?: DrapeDrawSegment): void;
+    /**
+     * Releases the resources
+     */
+    dispose(): void;
+    private bindData;
+    /** The tallest data texture this GPU allows (MAX_TEXTURE_SIZE, read once) */
+    private textureSizeLimit;
+    /**
+     * Allocates a data texture and transfers the rows that have not been sent yet
+     *
+     * texStorage2D is immutable, so the texture is recreated whenever the required
+     * size changes (once recreated, everything is sent again).
+     */
+    private uploadTexture;
+}