@sakuzu/maplibre-gl-draw 1.0.0

package/dist/view/layer/drape-planner.d.ts

@@ -0,0 +1,139 @@
+/**
+ * DrapePlanner
+ *
+ * Plans the analytic drape of a frame (the path that paints polygons and lines as ground
+ * pixels): whether it is used in this frame, the tiles it draws, and the datasets that hand
+ * their polygons and lines over to it. Every decision leaves its reason in the diagnostic values
+ * of the terrain context (`getTerrainDrapeDebug`):
+ *
+ * - `terrain-off`: there is no terrain
+ * - `wide-zoom`: the view is wider than the analytic band and the elements are too heavy for it
+ * - `no-drapeable-features` / `vertex-budget`: nothing to drape, or too much
+ * - `cell-overflow`: the tile index went over its budget
+ * - `no-dem-tiles`: no tile of the view has a DEM or an index yet
+ * - `stale-plan`: the previous plan is kept while the index of the view is being built
+ * - `texture-limit`: the tables do not fit in the textures of this GPU
+ * - `ok`: the plan was built from the tiles of this frame
+ *
+ * The state that carries over between frames (the collected elements, the tile index, the plan,
+ * the counters that keep the hand-over from flapping) lives here. The planner is created once
+ * per layer; the GPU side it holds (the drape renderers) is dropped by `releaseGpu`.
+ */
+import type { Map as MapLibreMap, ProjectionData } from 'maplibre-gl';
+import type { Store } from '../../store/store.js';
+import type { Feature } from '../../store/types.js';
+import type { RetainedStyleResolver } from '../renderers/retained.js';
+import type { TerrainContext } from '../terrain/context.js';
+import { type getMapTerrain } from '../terrain/detect.js';
+import { type DrapeDatasetSource } from '../terrain/drape/pass.js';
+import { type DrapeTileDraw } from '../terrain/drape/renderer.js';
+/** The terrain of the map as maplibre exposes it (null when there is none) */
+export type MapTerrain = ReturnType<typeof getMapTerrain>;
+/**
+ * Lower bound of the zoom at which the analytic drape is used
+ *
+ * A view wider than this is handled by the vertex displacement path and the fills are drawn
+ * without depth. There are three reasons.
+ *
+ * - Over a wide area the relief is only a dozen or so pixels on screen, so there is no benefit
+ *   in solving it as ground pixels (with the depth off, the punch-through of the vertex
+ *   displacement disappears by construction as well)
+ * - A wide-area tile holds all of the features, so the budget of the analytic evaluation is
+ *   often exceeded and it degenerates. Fixing the boundary by zoom keeps the paths from
+ *   flapping within the band (every flap re-bakes the retained batches, so the fills disappear
+ *   for a few seconds)
+ * - Over a wide area, building the index costs on the order of 20 ms per tile. Not going
+ *   through it reduces the stutter of zooming
+ */
+export declare const TERRAIN_ANALYTIC_MIN_ZOOM = 11;
+/**
+ * Number of consecutive frames before the analytic drape counts as "in use"
+ *
+ * A dataset drops its polygons and lines from the retained batch once it hands them to the
+ * drape, so if the decision to hand over flickers, the re-baking goes back and forth and the
+ * fills disappear. The hand-over happens only once things have settled, and it is taken back
+ * immediately once the drape can no longer be used (only one side is relaxed).
+ */
+export declare const DRAPE_STABLE_FRAMES = 10;
+/**
+ * Upper limit of the frames that may keep drawing with the previous plan while waiting for the
+ * index
+ *
+ * Even if the index stays unbuildable, the old plan must not be kept forever. Beyond 60 frames
+ * (about a second) it is redrawn with whatever could be built.
+ */
+export declare const DRAPE_STALE_PLAN_MAX_FRAMES = 60;
+/**
+ * Number of edges for which the analytic drape is allowed in a wide band
+ *
+ * Over a wide area one tile holds all of the features, so the cost of building the index is
+ * determined by the number of edges. A few thousand can be built in under a millisecond per
+ * tile.
+ */
+export declare const DRAPE_WIDE_EDGE_BUDGET = 20000;
+/** Per-tile draw instruction of the drape for this frame (with the stitching resolved) */
+export interface DrapeTileDrawEntry {
+    readonly draw: DrapeTileDraw;
+    readonly projection: ProjectionData;
+}
+/** An image interleaved into the stacking order (position in the element list and feature) */
+export interface PendingQuad {
+    readonly at: number;
+    readonly feature: Feature;
+}
+/** A dataset as the planner sees it (the drape part and its factors) */
+export interface DrapePlannerDataset extends DrapeDatasetSource {
+    /** The factors of the source at a zoom (opacity and size) */
+    drapeFactors(zoom: number): {
+        scale: number;
+        opacity: number;
+    };
+}
+/**
+ * The datasets as the planner sees them
+ *
+ * The manager in `display/manager.ts` satisfies this shape. Only the structure is declared here,
+ * so that the planner does not read a type from display/ (which sits above view/).
+ */
+export interface DrapePlannerDatasets {
+    listInternal(): readonly DrapePlannerDataset[];
+    /** Reports the datasets that hand their polygons and lines over to the drape */
+    setDrapedDatasets(ids: ReadonlySet<string> | null): void;
+}
+/** What the planner needs for the whole life of the layer */
+export interface DrapePlannerDeps {
+    map: MapLibreMap;
+    store: Store;
+    terrain: TerrainContext;
+    datasets?: DrapePlannerDatasets;
+    /**
+     * Whether the work that does not fit in a frame is spread over later frames (true when
+     * omitted; the `timeSlicing` of the rendering settings)
+     */
+    timeSlicing?: boolean;
+}
+/** The inputs of one frame */
+export interface DrapeFrameInput {
+    gl: WebGL2RenderingContext;
+    /** The style resolver the elements are collected with (called only when they are collected) */
+    resolveStyles: () => RetainedStyleResolver;
+    /** The terrain of the map (null when the terrain state of the frame is inactive) */
+    mapTerrain: MapTerrain;
+    dpr: number;
+    /** The style zoom (what the rendering reads) */
+    zoom: number;
+    /** The real zoom of the camera (the band is decided with it) */
+    rawZoom: number;
+}
+/** The draw instructions of the analytic drape for one frame */
+export interface DrapeFrameDraws {
+    /** Whether the drape can be drawn (the shaders and the plan are ready) */
+    readonly ready: boolean;
+    readonly tileDraws: DrapeTileDrawEntry[];
+    readonly pendingQuads: PendingQuad[];
+    /**
+     * When the drape could not be built, a slot is needed to draw the images that were to be
+     * interleaved between the sections
+     */
+    readonly fallbackQuads: Feature[];
+}