@sakuzu/maplibre-gl-draw 1.0.0

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

@@ -0,0 +1,259 @@
+/**
+ * The CPU-side precomputation (binning) for the analytic drape
+ *
+ * The fragment shader solves "is this pixel inside the feature, and how far is
+ * it from an edge" on the spot every time. Sweeping every edge of every feature
+ * for each pixel is impossible, so the inside of a tile is cut into a coarse
+ * grid (grid x grid) and, for each cell, "the list of edges that touch that
+ * cell" and "whether the origin of the cell is inside that feature" are
+ * computed in advance.
+ *
+ * The inside/outside test for a pixel starts from "the inside/outside of the
+ * cell origin" and is decided by the number of crossings between the edges and
+ * the segment drawn from the cell origin to the pixel. The segment fits
+ * entirely inside the cell, so an edge that could cross it is always in the
+ * list of that cell (because every cell an edge passes through gets it). This
+ * is what keeps the inside/outside test from breaking when edges are thinned.
+ *
+ * The resolution of the grid is decided per tile. The polygons and lines of
+ * datasets are now placed here as well, and the number of edges
+ * touching a single tile therefore varies by three orders of magnitude. With a
+ * fixed 8x8, thousands of edges would go into a single cell and exceed the
+ * budget; conversely, applying a fine grid to every tile makes the index alone
+ * bloat on empty tiles.
+ *
+ * The amount of scanning is proportional to "the edges relevant to the tile".
+ * Elements are dropped by their bounding box, and edges are dropped by the
+ * bounding box of chunks of 64 edges (the blocks in geometry.ts), so even for a
+ * dataset with a million vertices the work per tile amounts only to the
+ * outlines that run through it. This runs on edit and when a new tile enters
+ * the view, and only then (not every frame; `bin-store.ts` caches per tile).
+ */
+import type { DrapeBounds, DrapeGeometry } from './geometry.js';
+/** The minimum number of divisions of the grid (per side) */
+export declare const DRAPE_MIN_CELLS = 8;
+/** The maximum number of divisions of the grid (per side) */
+export declare const DRAPE_MAX_CELLS = 64;
+/**
+ * The maximum number of divisions of the grid (per side) allowed on a retry
+ *
+ * Only when cells that exceed the budget remain is the grid made this fine and rebuilt.
+ */
+export declare const DRAPE_RETRY_MAX_CELLS = 128;
+/**
+ * The target number of edges to put into one cell (the grid is made finer so as not to exceed it)
+ *
+ * It is set at half of the upper limit of the work per pixel (DRAPE_MAX_CELL_WORK). If the
+ * target were the same as the limit, even a single straightforward feature would sit right at
+ * the limit and unnecessary quantization would be applied.
+ */
+export declare const DRAPE_TARGET_EDGES_PER_CELL = 12;
+/** The target number of elements to put into one cell (this decides the number of runs) */
+export declare const DRAPE_TARGET_ELEMENTS_PER_CELL = 4;
+/** The maximum number of edges one cell can hold (a cell that exceeds it signals degradation) */
+export declare const DRAPE_MAX_EDGES_PER_CELL = 256;
+/**
+ * The maximum number of runs (the span of one feature) one cell can hold
+ *
+ * A cell that exceeds it is truncated inside that cell alone (the elements at the back of the
+ * draw order = in front are dropped). The only cells this applies to are those of a coarse
+ * distant tile where dozens of items overlap in a single pixel. The map as a whole is never
+ * degraded.
+ */
+export declare const DRAPE_MAX_RUNS_PER_CELL = 128;
+/**
+ * The maximum number of edges handled by a single tile
+ *
+ * First the vertices are quantized onto a grid (LOD) to make them fit. A tile that still
+ * exceeds the limit is not built and returns the degradation signal instead (discarding it
+ * after building would stall the frame for exactly that long).
+ *
+ * The value was taken from measurements. Putting 8,172 administrative boundaries (about 1.1
+ * million vertices) through a single tile, building the index takes 0.8ms at z13, 1.2ms at
+ * z12, 4.0ms at z11, 15.6ms at z10 and 23.4ms at z9. 200,000 edges is roughly 20ms, and the
+ * only tiles that reach this amount are the coarse ones, of which there are just a few in the
+ * view (they are built only once, and after that the cache of the tile index takes over). The
+ * amount for the whole view is held down separately by the budget of the edge texture
+ * (DRAPE_MAX_EDGE_TEXELS in bin-store).
+ */
+export declare const DRAPE_MAX_EDGES_PER_TILE = 200000;
+/**
+ * The upper limit of the amount solved per cell (the average of runs + edges)
+ *
+ * A fragment walks the runs of its own cell in order and, for each run, sweeps the edges of
+ * that cell. The work per pixel is therefore roughly "the number of runs + the number of edges
+ * of that cell". When the map is zoomed far out, nested administrative areas (prefectures,
+ * districts, municipalities) and neighboring areas pile up dozens deep in a single cell and
+ * this amount jumps. In measurements it reached 500ms per frame over the whole Kanto region at
+ * z8.7.
+ *
+ * A tile that exceeds this is not suited to the analytic evaluation. The vertex displacement
+ * path takes it over (in a zoomed-out view the relief of the terrain is small on screen, so
+ * vertex displacement does not break down either).
+ *
+ * The actual limit is scaled up by the number of tiles in the view. The screen is shared out
+ * among the tiles, so the more tiles there are the fewer pixels each one has, and the same
+ * work per pixel costs less for the frame as a whole (`drapeCellWorkBudget`).
+ */
+export declare const DRAPE_MAX_CELL_WORK = 24;
+/**
+ * Derives the upper limit of the work per cell from the number of tiles in the view
+ */
+export declare function drapeCellWorkBudget(tileCount: number): number;
+/**
+ * The number of edges at which the vertices start being quantized onto a grid
+ *
+ * A tile below this solves the original geometry as it is (every view at a normal zoom is on
+ * this side, and quantization applies only to coarse distant tiles).
+ */
+export declare const DRAPE_LOD_TRIGGER = 16000;
+/** The color (0..1, with the opacity already folded in) */
+export type DrapeColor = readonly [number, number, number, number];
+/**
+ * An element handed to the analytic drape (a feature of the Store and a feature of a
+ * dataset have the same shape)
+ */
+export interface DrapeElement {
+    /** 0 = polygon, 1 = line */
+    readonly kind: 0 | 1;
+    /** The bounding box in Mercator (this alone is enough to narrow the tiles down) */
+    readonly bounds: DrapeBounds;
+    /**
+     * The geometry in Mercator coordinates (built at the point it becomes necessary)
+     *
+     * The coordinates of a feature that does not enter the view are not converted. Converting
+     * every feature up front comes as a single hit of 76ms for 1.1 million vertices (measured).
+     */
+    geometry(): DrapeGeometry;
+    /** The color of the fill (lines do not use it) */
+    readonly fill: DrapeColor;
+    /** The color of the outline */
+    readonly stroke: DrapeColor;
+    /** The width of the outline (physical pixels). 0 means the outline is not drawn */
+    readonly strokeWidthPx: number;
+    /**
+     * The origin of the coefficients (0 = the Store, 1 and above = datasets)
+     *
+     * The zoom-linked opacity and scale change from frame to frame, so instead of being baked
+     * into the element they are applied through a uniform at draw time. Baking them in would
+     * mean redoing the binning of every tile each time the zoom moves.
+     */
+    readonly source: number;
+    /**
+     * The reference zoom of the line width (an element without one has -1 = fixed in screen pixels)
+     *
+     * The retained batch path changes the thickness by `2^(zoom - createdZoom)`, so the drape
+     * applies the same formula in the shader as well (the thickness does not change with or
+     * without the terrain).
+     */
+    readonly widthZoom: number;
+    /**
+     * The identifier of the selection highlight (an empty string = not a target of highlighting)
+     *
+     * Only a feature of a dataset has one. A selection changes with a single
+     * click, whereas the index (the binning) is rebuilt only on edit and when the view swaps
+     * tiles. The selection therefore cannot be baked into the element, and instead a single texel
+     * of the style table is rewritten on every draw (`setSelection` in `bin-store.ts`). This is
+     * the key used to match them up.
+     *
+     * A feature of the Store uses an empty string. A selection in the Store is expressed by the
+     * selection UI (the box and the handles) rather than by a red overpaint, so the drape never
+     * changes its color.
+     */
+    readonly selectionKey: string;
+}
+/**
+ * The break of the stacking order (the position of an image)
+ *
+ * An image (Image) is not carried by the analytic evaluation (a texture cannot be brought into
+ * the per-pixel compositing loop), but it can be pasted onto the ground surface by the quad
+ * drape. To preserve the stacking order it is enough to split the element list at the position
+ * of an image and draw each section by range, slipping the image in between. The position of
+ * that break is remembered at the time of dataset.
+ *
+ * The position is an index within the ordering of the elements, so it must always be handled
+ * together with the element list of the same version (drawing an old index with a new break
+ * while the version of the index is being swapped would paint a different element, or paint
+ * nothing at all). That is why `bin-store.ts` holds it together with the element list.
+ */
+export interface DrapeQuadBreak {
+    /** The feature ID of the image */
+    readonly featureId: string;
+    /** The number of elements stacked below this image (= the position of the break) */
+    readonly afterElements: number;
+}
+/**
+ * Builds the key of the selection highlight
+ *
+ * So that IDs colliding across datasets are never mistaken for one another, the dataset
+ * ID and the feature ID are tied together with a delimiter. The side that builds the elements
+ * (`pass.ts`) and the side that collects the selection (`view/layer/drape-planner.ts`) use the
+ * same function.
+ */
+export declare function drapeSelectionKey(datasetId: string, featureId: string): string;
+/** The binning result for a single tile */
+export interface TileBins {
+    /** The number of divisions of the grid (per side) */
+    readonly grid: number;
+    /** (runStart, runCount) per cell. Length = grid * grid * 2 */
+    readonly cells: Int32Array;
+    /** (elementIndex, edgeStart, edgeCount, baseInside) per run */
+    readonly runs: Float32Array;
+    /** (x0, y0, x1, y1) per edge. In-tile 0..1 coordinates */
+    readonly edges: Float32Array;
+    /** Whether a limit was exceeded (if it was, the caller degrades) */
+    readonly overflow: boolean;
+    /** The number of cells truncated for exceeding the budget (a local degradation. Diagnostic) */
+    readonly truncatedCells: number;
+    /** The average amount solved per cell (runs + edges). A guide to the cost of the fragment */
+    readonly cellWork: number;
+    /** The estimate of the edges relevant to this tile (used for diagnostics and budget checks) */
+    readonly edgeEstimate: number;
+    /** The largest number of edges that went into one cell (diagnostic) */
+    readonly maxEdgesPerCell: number;
+    /** The largest number of runs that went into one cell (diagnostic) */
+    readonly maxRunsPerCell: number;
+}
+/** The identity of a tile */
+export interface DrapeTile {
+    readonly x: number;
+    readonly y: number;
+    readonly z: number;
+}
+/**
+ * The margin of an element (in-tile coordinates)
+ *
+ * A line is drawn with a thickness in screen pixels, so even an edge outside a cell paints
+ * pixels inside the cell. This is the margin used to hand that reach out to the cells. For an
+ * element that has a reference zoom the thickness changes by `2^(zoom - widthZoom)`, so the
+ * same factor is applied to the estimate as well. Forgetting to apply it eats the fringe of a
+ * thickened, zoomed-in line at the cell boundaries and chips it away into a jagged edge.
+ *
+ * @param strokeWidthPx The thickness at the reference zoom (physical pixels)
+ * @param widthZoom The reference zoom of the thickness (negative means fixed in screen pixels)
+ * @param zoom The current zoom
+ */
+export declare function drapeMarginOf(strokeWidthPx: number, widthZoom?: number, zoom?: number): number;
+/**
+ * Decides the number of divisions of the grid (a power of two)
+ *
+ * From the number of edges it picks a resolution that fits within "the target number per cell",
+ * and holds it back to the range where a cell does not become smaller than the margin (if the
+ * margin were larger than a cell, a single edge would be scattered as far as the cell after
+ * the next one and only the index would bloat).
+ */
+export declare function chooseGrid(edgeCount: number, margin: number, elementCount?: number): number;
+/**
+ * Performs the binning for a single tile
+ *
+ * @param elements The elements in draw order (the whole ordering. The index becomes the row of
+ *   the style)
+ * @param tile The tile
+ * @param candidates The indices of the elements narrowed down in advance (when omitted, every
+ *   element is looked at)
+ */
+export declare function binTile(elements: readonly DrapeElement[], tile: DrapeTile, options?: {
+    candidates?: readonly number[];
+    maxCellWork?: number;
+    zoom?: number;
+}): TileBins;