@tangram.gl/basemap-layers 0.0.0-stage → 0.0.1

package/dist/types/globe-layers.d.ts

@@ -0,0 +1,239 @@
+import type { GlyphStore } from "./glyph-store.js";
+import { SharedMVTLayer, SharedTileset2D } from '@deck.gl-community/geo-layers';
+import { type DemTile } from "./hillshade-layer.js";
+import type { LabelPlacement } from "./label-placement.js";
+import { type StyleAccessor } from "./style-accessor.js";
+import { ZoomPaint, type ZoomPaintValues } from "./zoom-paint-extension.js";
+import type { BasemapGlobeConfig, BasemapLayerProps } from "./basemap-layer.js";
+import type { SpriteAtlas } from "./sprite.js";
+import type { LabelFontFamily } from "./text-font.js";
+import type { BasemapLoadOptions, BasemapSource, ResolvedBasemapStyleLayer as BasemapStyleLayer, ResolvedBasemapStyle } from "./style-resolver.js";
+type BasemapMode = NonNullable<BasemapLayerProps['mode']>;
+type BasemapLayerConfig = {
+    atmosphere: boolean;
+    basemap: boolean;
+    labels: boolean;
+};
+type BasemapLayerGroup = {
+    idPrefix?: string;
+    mode?: BasemapMode;
+    globe?: {
+        config?: BasemapGlobeConfig;
+    };
+    styleDefinition: ResolvedBasemapStyle;
+    zoom?: number;
+    loadOptions?: BasemapLoadOptions;
+    /**
+     * Sprites loaded for the style; symbol layers draw `icon-image` from them. `null` means the
+     * sprites are still loading: no icons are drawn, and labels are placed as if each symbol had its
+     * icon. Omit it, or pass `[]`, for a style without sprites.
+     */
+    spriteAtlases?: SpriteAtlas[] | null;
+    /** Overrides the label font that `text-font` maps to (see `BasemapLayerProps.fontFamily`). */
+    fontFamily?: LabelFontFamily | null;
+    /** The style's glyphs, which labels are drawn with (see `MVTLabelLayerProps.glyphs`). */
+    glyphs?: GlyphStore | null;
+    /** The label placement shared by the map's label layers (see `LabelPlacement`). */
+    labelPlacement?: LabelPlacement | null;
+    /** Externally owned source caches; BasemapLayer supplies and finalizes these. */
+    tilesets?: Map<BasemapSource, SharedTileset2D>;
+};
+/**
+ * Style layers that draw together, in style order: a background, raster or hillshade layer on its
+ * own, or consecutive style layers of one vector source, which share one tile layer.
+ */
+export type StyleLayerRun = {
+    type: 'background' | 'raster' | 'hillshade' | 'vector';
+    /** The deck.gl layer id, without the basemap's id prefix. */
+    id: string;
+    sourceId?: string;
+    source?: BasemapSource;
+    styleLayers: BasemapStyleLayer[];
+};
+/** The `minzoom`/`maxzoom` limits that `isStyleLayerVisibleAtZoom` compares against. */
+export declare function getStyleZoomLimits(styleLayers: BasemapStyleLayer[]): (number | undefined)[];
+/**
+ * Evaluates the paint of style layers drawn by one sublayer for `ZoomPaintExtension`: a style
+ * layer's width, or 1 where it is per feature, and its colors in 0-1, or an alpha of -1 where they
+ * are per feature.
+ */
+export declare function getZoomPaintValues(styleLayers: BasemapStyleLayer[], mode: BasemapMode, zoom: number): ZoomPaintValues;
+/**
+ * The paint of one tile layer's fill and line sublayers for `ZoomPaintExtension`: the zoom its
+ * sublayers were generated at, and a `ZoomPaint` per sequence of style layers drawn by one
+ * sublayer, shared by all tiles. Kept in the tile layer's state.
+ */
+export declare class ZoomPaintContext {
+    /** The stepped zoom (see `getZoomBucket`) at which paint is evaluated. */
+    zoom: number;
+    private zoomPaints;
+    /** The style the zoom paints were made for (see `setStyle`). */
+    private style;
+    /** The zoom paints no sublayer has asked for since the last style change. */
+    private unused;
+    /**
+     * Destroys the zoom paints of sequences of style layers that no sublayer drew with since the
+     * previous style change. A new style keeps the zoom paints of the style layers it keeps, and its
+     * tile sublayers, regenerated, ask for the others again, so at most one style's are left over.
+     */
+    setStyle(style: unknown): void;
+    /**
+     * The `ZoomPaint` of style layers drawn by one sublayer. Its values are evaluated once per zoom
+     * step, and again when a paint property is replaced.
+     */
+    get(styleLayers: BasemapStyleLayer[], mode: BasemapMode): ZoomPaint;
+    /** Releases the textures of every `ZoomPaint`. */
+    destroy(): void;
+}
+/**
+ * The `zoomOffset` of vector sources' tiles. MapLibre GL JS draws a vector source with the tiles
+ * at the floor of the zoom (and a raster source with those at the rounded zoom, as deck.gl's
+ * `TileLayer` does): its styles and labels are laid out for that. Half a zoom down before
+ * rounding selects the same tiles.
+ */
+export declare const VECTOR_TILE_ZOOM_OFFSET = -0.5;
+/**
+ * The tile pyramid range of a source. `TileLayer` draws nothing at a view zoom below its `minZoom`,
+ * unless it has an `extent`. On a globe, the view zoom goes below 0 near the poles: `GlobeView`
+ * lowers the zoom with the latitude, so that the globe keeps its size on screen (zoom 0 at the
+ * equator is zoom -2 at latitude 76). A source whose pyramid starts at zoom 0 draws its zoom 0
+ * tiles at any lower zoom, as in MapLibre; the extent, the whole pyramid, selects them.
+ */
+export declare function getTilePyramidProps(source: BasemapSource): {
+    minZoom: number;
+    maxZoom: number;
+    extent: number[] | null;
+};
+/**
+ * Creates the tileset of a `raster-dem` source: each tile is fetched and decoded once, and shared by
+ * every `hillshade` layer drawn from it. `BasemapLayer` creates and finalizes these itself. Direct
+ * `getBasemapLayers` callers that call it on every render pass them in `tilesets`, keyed by source,
+ * to keep the tiles across calls, and finalize them when done.
+ */
+export declare function createDemTileset(source: BasemapSource, loadOptions?: BasemapLoadOptions): SharedTileset2D<DemTile | null>;
+/**
+ * Orders the sublayers of all tiles of a tile layer by style layer, as MapLibre draws each style
+ * layer across all tiles before the next: a tile's fills cannot paint over the labels of the tile
+ * drawn before it. Within a style layer, tiles keep their order, and so do the sublayers of a tile.
+ */
+export declare function sortTileSubLayers<LayerT extends {
+    props: Record<string, any>;
+}>(tileSubLayers: (LayerT[] | null | undefined)[]): LayerT[];
+/**
+ * Whether two sets of layer props are the same to deck.gl. Per-feature accessors (`get*`) that
+ * are both functions count as the same, unless `accessors` is false: with the same data, deck.gl
+ * reads them again only when their update trigger, compared with the other props, changes.
+ */
+export declare function isSameProps(a: Record<string, any>, b: Record<string, any>, depth?: number, accessors?: boolean): boolean;
+/** All style-layer `minzoom`/`maxzoom` limits in a style. */
+export declare function getStyleDefinitionZoomLimits(styleDefinition: BasemapLayerGroup['styleDefinition']): (number | undefined)[];
+export declare function getBasemapLayers({ idPrefix, mode, globe, styleDefinition, zoom, loadOptions, spriteAtlases, fontFamily, glyphs, labelPlacement, tilesets }: BasemapLayerGroup): any[];
+export declare function getGlobeBaseLayers({ globe, styleDefinition, idPrefix, zoom, loadOptions, spriteAtlases, fontFamily, glyphs, labelPlacement }: Omit<BasemapLayerGroup, 'mode'>): any[];
+export declare function getGlobeTopLayers({ globe }: {
+    globe: {
+        config: BasemapGlobeConfig;
+    };
+}): null[];
+/**
+ * Converts a style `line-dasharray` into deck.gl's `[dash, gap]`. MapLibre measures dashes in line
+ * widths; deck.gl's `widths` unit is half the line width, so lengths double. deck.gl draws one dash
+ * and one gap per period, so a longer pattern keeps its period and total dash length, but merges
+ * its dashes. In an odd-length pattern the last dash runs into the first, as in MapLibre. An empty
+ * pattern, or one without gaps, draws a solid line.
+ */
+export declare function getDashArray(dasharray: unknown): [number, number];
+/** The least distance, in pixels, of a gap's line from the gap's center: see getLineOffset. */
+export declare const MIN_GAP_LINE_CENTER = 0.01;
+/**
+ * Converts `line-offset` and `line-gap-width` into deck.gl's `getOffset`, which is in line widths.
+ * A gap draws two lines of `width` with their centers `gapWidth / 2 + width / 2` either side of
+ * the offset line: `side` is 1 or -1 for them. Without a gap, `side` is ignored. Positive is to
+ * the right of the line's direction in both. Dividing by `width` assumes deck.gl draws the line
+ * `width` pixels wide, that is, no `lineWidthMinPixels`/`lineWidthMaxPixels` clamp applies.
+ *
+ * deck.gl offsets by widening the stroke and masking it across the line, not by offsetting the
+ * path, so the outside of a sharp corner breaks open and the two lines of a gap end in separate
+ * stubs rather than one cap. Offsetting the path belongs in deck.gl's `PathStyleExtension`.
+ */
+export declare function getLineOffset(offset: number, gapWidth: number, width: number, side: number, blur?: number): number;
+/**
+ * Scales a blurred gap's `getDashArray` by `width / drawnWidth` (see `getBlurredLineWidth`), so
+ * that its dashes keep the pixel lengths MapLibre gives them in `line-width`s. `shape` is the
+ * `[offset, gap, width, blur]` accessor of `getLineOffset`.
+ */
+export declare function getBlurredDashArray(dashArray: StyleAccessor<[number, number]>, shape: StyleAccessor<[number, number, number, number]>): {
+    value: [number, number] | ((feature: any) => [number, number]);
+    updateTrigger?: unknown[];
+};
+/** deck.gl path props for a line's `line-cap`, `line-join` and `line-miter-limit`. */
+export type LineShape = {
+    lineCapRounded: boolean;
+    lineJointRounded: boolean;
+    lineMiterLimit: number;
+};
+/**
+ * Converts `line-cap`, `line-join` and `line-miter-limit` into deck.gl path props.
+ *
+ * - `round` caps and joins are drawn round. `butt` caps end at the endpoint. deck.gl has no square
+ *   cap, so `square` is drawn as `butt`: the line ends half its width short of MapLibre's.
+ * - deck.gl cuts a joint flat at `miterLimit + 1` half widths from the vertex. MapLibre draws a
+ *   `miter` join in full while its tip is within `line-miter-limit` half widths of the vertex, so
+ *   passing `line-miter-limit - 1` draws the same joins in full. A sharper corner, which MapLibre
+ *   bevels, is cut flat at that distance instead.
+ * - deck.gl has no bevel join. A `bevel` join is cut flat half the line width from the vertex,
+ *   which matches a bevel at shallow corners; at sharp corners a true bevel cuts closer.
+ */
+export declare function getLineShape([cap, join, miterLimit]: unknown[]): LineShape;
+/**
+ * One accessor for the features of several style layers: a constant when every style layer's
+ * value is the same constant, otherwise a function that applies each feature's own style layer's
+ * accessor. Its update trigger changes when any style layer's value or trigger changes.
+ */
+export declare function mergeStyleAccessors<T>(accessors: StyleAccessor<T>[], partIndices: ArrayLike<number>): {
+    value: T | ((feature: any, info: {
+        index: number;
+    }) => T);
+    updateTrigger?: unknown;
+};
+/**
+ * Whether a source's layers draw from vector tiles: a vector source with tile templates, or a
+ * GeoJSON source with data, which is cut into tiles on the client (see `getGeoJsonTileFeatures`).
+ */
+export declare function isVectorTileSource(source: BasemapSource | undefined): boolean;
+/**
+ * The `getTileData` of a vector tile source's tileset: `loader` fetches and decodes a vector
+ * source's tiles, and a GeoJSON source's tiles are cut from its data, in the same tile-local
+ * coordinates.
+ */
+export declare function getVectorTileLoader(source: BasemapSource, loader: SharedMVTLayer): (tile: Parameters<SharedMVTLayer['getTileData']>[0]) => Promise<any>;
+/**
+ * The source layers drawn from each vector source, over all of its runs, sorted; `null` for a
+ * source with a style layer that names none. Tiles decode only these: OpenMapTiles tiles, for
+ * one, carry house numbers and peaks that few styles draw, and points of interest, most of a
+ * street-level tile, that a style without them, or with labels off, does not draw.
+ */
+export declare function getRunSourceLayers(runs: StyleLayerRun[]): Map<BasemapSource, string[] | null>;
+/**
+ * The source layers each vector source of a style decodes (see `getRunSourceLayers`). With the
+ * basemap off they are those it would draw, so that turning it off and on keeps the tiles.
+ */
+export declare function getStyleSourceLayers(styleDefinition: ResolvedBasemapStyle, globe?: {
+    config?: BasemapGlobeConfig;
+}): Map<BasemapSource, string[] | null>;
+/**
+ * `loadOptions` for a vector source's tiles, decoding only `sourceLayers` when given. Source
+ * layers set in `loadOptions.mvt.layers` are left as they are.
+ */
+export declare function getSourceLoadOptions(loadOptions: BasemapLoadOptions | undefined, sourceLayers: string[] | null | undefined): BasemapLoadOptions | undefined;
+/**
+ * Splits the style into runs that draw in style order, as in MapLibre: each background, raster
+ * and hillshade layer on its own, and consecutive layers of one vector source together, so that a
+ * raster layer between two vector layers draws between them. Layers that cannot draw (a source
+ * without tiles, labels turned off) do not split a run. Runs do not depend on zoom, so the tile
+ * layers keep their ids and tiles when a layer leaves its zoom range. Background, raster and
+ * hillshade runs have their style layer's id. The first run of a source has the source id as its
+ * id, unless a background, raster or hillshade run already has that id; later runs, and a first run whose source id is
+ * taken, add the quoted id of their first style layer.
+ */
+export declare function getStyleLayerRuns(styleLayers: BasemapStyleLayer[], styleDefinition: ResolvedBasemapStyle, config?: BasemapLayerConfig): StyleLayerRun[];
+export {};

package/dist/types/globe-line-angle-extension.d.ts

@@ -0,0 +1,37 @@
+import { LayerExtension } from '@deck.gl/core';
+import type { Layer } from '@deck.gl/core';
+/**
+ * Keeps billboards drawn along lines (labels and icons whose rotation is aligned to the map) on
+ * their lines in a `GlobeView`, which draws them in screen space: their angles are taken from
+ * north up, and the shader turns them as the view draws the line, upright with `keepUpright`. In
+ * other views it does nothing. Add it only to billboards (the shader would also turn the offset of
+ * a layer drawn in the map plane) whose angle is a direction on the map. WebGL only: on WebGPU the
+ * extension adds no shader code, and they stay as they are drawn from north up.
+ *
+ * Added to a composite layer such as `TextLayer`, it reaches the character and background
+ * sublayers. With `keepOffsetSide`, text kept upright is turned around without its pixel offset,
+ * which must then be a direction along and across the line, as `text-offset` is.
+ */
+export declare class GlobeLineAngleExtension extends LayerExtension<{
+    keepUpright: boolean;
+    keepOffsetSide?: boolean;
+}> {
+    static extensionName: string;
+    constructor(opts: {
+        keepUpright: boolean;
+        keepOffsetSide?: boolean;
+    });
+    getShaders(this: Layer, extension: GlobeLineAngleExtension): {
+        modules?: undefined;
+    } | {
+        modules: {
+            name: string;
+            dependencies: import("@luma.gl/shadertools").ShaderModule[];
+            inject: {
+                'vs:#decl': string;
+                'vs:#main-start': string;
+                'vs:DECKGL_FILTER_SIZE': string;
+            };
+        }[];
+    };
+}

package/dist/types/glyph-font-renderer.d.ts

@@ -0,0 +1,37 @@
+import type { TextLayerProps } from '@deck.gl/layers';
+import type { Glyph } from "./glyph-pbf.js";
+import type { GlyphStore } from "./glyph-store.js";
+type GetFontRenderer = NonNullable<TextLayerProps['_getFontRenderer']>;
+type FontRenderer = ReturnType<GetFontRenderer>;
+/**
+ * `TextLayer`'s font settings for glyphs from a style's `glyphs` URL: distance fields one em of
+ * {@link GLYPH_EM} pixels high, reaching 8 pixels, with the edge at 0.75, as MapLibre GL JS draws
+ * them. Cells are packed `buffer` pixels apart, the border of the glyph bitmaps.
+ */
+export declare const GLYPH_FONT_SETTINGS: {
+    sdf: boolean;
+    fontSize: number;
+    buffer: number;
+    radius: number;
+    cutoff: number;
+    smoothing: number;
+};
+/**
+ * The glyph a character of `fontStack` is drawn with: from the store's ranges, or with the browser's
+ * fonts for the characters MapLibre GL JS draws so. Null while its range loads, and when the range
+ * has none: the character is then not drawn, as in MapLibre.
+ */
+export declare function getStyleGlyph(store: GlyphStore, fontStack: string, character: string): Glyph | null;
+/**
+ * A function giving a character's advance in ems: the glyph's advance, as MapLibre GL JS lays text
+ * out. A character without a glyph advances nothing.
+ */
+export declare function getGlyphCharacterMeasurer(store: GlyphStore, fontStack: string): (character: string) => number;
+/**
+ * `TextLayer`'s font renderer for the glyphs of a font stack. With
+ * {@link GLYPH_FONT_SETTINGS}, `TextLayer` lays each character's glyph out as MapLibre GL JS does:
+ * the line's baseline offset puts it {@link LINE_GLYPH_OFFSET} pixels below the line's top, and the
+ * glyph's bitmap is drawn `top` pixels below that and `left` pixels right of the pen.
+ */
+export declare function getGlyphFontRenderer(store: GlyphStore, fontStack: string): FontRenderer;
+export {};

package/dist/types/glyph-pbf.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The pixels of distance field around each glyph of a glyph range, on every side, beyond its
+ * `width` and `height`: a bitmap is `width + 6` by `height + 6`.
+ */
+export declare const GLYPH_BORDER = 3;
+/** The size, in pixels, at which glyph ranges are drawn: one em. */
+export declare const GLYPH_EM = 24;
+/** Code points per glyph range: a range file holds `256 * n` to `256 * n + 255`. */
+export declare const GLYPH_RANGE_SIZE = 256;
+/**
+ * A glyph of a glyph range, as MapLibre GL JS reads it: a signed distance field and its metrics,
+ * in pixels at {@link GLYPH_EM}.
+ */
+export type Glyph = {
+    /** Unicode code point. */
+    id: number;
+    /**
+     * One byte per pixel, `width + 2 * GLYPH_BORDER` by `height + 2 * GLYPH_BORDER`; empty for a
+     * glyph without ink, such as a space.
+     */
+    bitmap: Uint8Array | Uint8ClampedArray;
+    /** Width of the ink. */
+    width: number;
+    /** Height of the ink. */
+    height: number;
+    /** From the pen position to the left of the ink. */
+    left: number;
+    /** Vertical bearing of the top of the ink, as MapLibre GL JS reads it. */
+    top: number;
+    /** From the pen position to the next. */
+    advance: number;
+};
+/**
+ * Reads a glyph range, the `{fontstack}/{range}.pbf` file a style's `glyphs` URL points to: the
+ * glyphs of every font stack it holds. Glyphs whose bitmap does not match their size are skipped.
+ */
+export declare function parseGlyphRange(data: ArrayBuffer | Uint8Array): Glyph[];

package/dist/types/glyph-store.d.ts

@@ -0,0 +1,103 @@
+import type { Glyph } from "./glyph-pbf.js";
+/** Options for a {@link GlyphStore}. */
+export type GlyphStoreOptions = {
+    /** The style's `glyphs` URL, with `{fontstack}` and `{range}`. */
+    url: string;
+    /** Base URL that a relative `glyphs` URL resolves against, normally the style URL. */
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    fetchOptions?: RequestInit;
+};
+/**
+ * Bound on the font stacks a store keeps glyphs for: stacks come from untrusted style and tile
+ * data. When full, the stack used least recently is dropped, and loaded again if asked for,
+ * unless a consumer retains it (see {@link GlyphStore.retain}).
+ */
+export declare const MAX_GLYPH_STACKS = 64;
+/** Bound on the font stacks one consumer, such as a label layer, can retain. */
+export declare const MAX_RETAINED_GLYPH_STACKS: number;
+/**
+ * Bound on the font stacks all the consumers of a store can retain together: the store never
+ * holds more than these, or {@link MAX_GLYPH_STACKS} when more.
+ */
+export declare const MAX_STORE_RETAINED_GLYPH_STACKS: number;
+/**
+ * Whether MapLibre GL JS draws a character with the browser's fonts rather than the style's
+ * glyphs: CJK ideographs, hangul, hiragana and katakana, by default (`localIdeographFontFamily`).
+ */
+export declare function isLocalGlyph(codePoint: number): boolean;
+export declare class GlyphStore {
+    /**
+     * Names this store among others, as of a style loaded again: a new store for the same URL holds
+     * none of the glyphs this one loaded.
+     */
+    readonly id: number;
+    readonly url: string;
+    private readonly fetch;
+    private readonly fetchOptions?;
+    private readonly stacks;
+    /** The font stacks each consumer retains (see `retain`). */
+    private readonly retained;
+    /** The number of consumers that retain each font stack retained. */
+    private readonly retainCounts;
+    /** Called once when a consumer next gives back a font stack (see `onRetainedFreed`). */
+    private readonly freedListeners;
+    constructor({ url, baseUrl, fetch: fetchFn, fetchOptions }: GlyphStoreOptions);
+    /**
+     * The glyph of a code point: `undefined` while its range is not loaded, `null` when the range
+     * has no glyph for it.
+     */
+    getGlyph(fontStack: string, codePoint: number): Glyph | null | undefined;
+    /** Whether the ranges of every code point of `text` are loaded, except local glyphs. */
+    hasGlyphs(fontStack: string, text: string): boolean;
+    /**
+     * Loads the ranges of the code points of `texts` that are not loaded yet. Resolves when they
+     * are, or have failed; returns null when there is nothing to load.
+     */
+    load(fontStack: string, texts: Iterable<string>): Promise<void> | null;
+    /**
+     * Keeps the glyphs of `fontStack` for `owner` until it gives the stack back (see `retainOnly`
+     * and `release`). A label layer retains the font stack of each label it draws or waits for
+     * before it loads any, so that loading some of them does not drop the others: a batch of
+     * labels in more than {@link MAX_GLYPH_STACKS} font stacks could otherwise never load.
+     *
+     * Returns false when the stack cannot be retained: `owner` retains
+     * {@link MAX_RETAINED_GLYPH_STACKS} stacks already, or the store's consumers
+     * {@link MAX_STORE_RETAINED_GLYPH_STACKS}. Font stacks come from untrusted tile data, so
+     * those bounds hold whatever a tile names; a label layer leaves the labels of a font stack it
+     * cannot retain undrawn, as those of a glyph range that fails to load.
+     */
+    retain(owner: object, fontStack: string): boolean;
+    /** Gives back the font stacks `owner` retains other than `fontStacks` (see `retain`). */
+    retainOnly(owner: object, fontStacks: ReadonlySet<string>): void;
+    /** Gives back the font stacks `owner` retains (see `retain`). */
+    release(owner: object): void;
+    /**
+     * Counts the times a consumer gave back font stacks: a `retain` refused before may succeed
+     * once it has changed.
+     */
+    generation: number;
+    /**
+     * Calls `listener` once, the next time a consumer gives back font stacks, in place of the
+     * listener `owner` set before; null removes it. A label layer whose font stacks were refused
+     * updates again then, to retain and load them.
+     */
+    onRetainedFreed(owner: object, listener: (() => void) | null): void;
+    /**
+     * The URL of a range: the font names of the stack, each URL-encoded, joined by commas. Font
+     * stacks can come from tile data (a data-driven `text-font`), so a name cannot add path
+     * segments, a query or a fragment to the URL.
+     */
+    getRangeUrl(fontStack: string, range: number): string;
+    private loadRange;
+    private getStack;
+    /**
+     * Drops the font stacks used least recently, beyond the bound, except those retained and
+     * `keep`, which is being loaded.
+     */
+    private evict;
+    private isRetained;
+    private unretain;
+}
+/** The index of the range that holds a code point. */
+export declare function getGlyphRange(codePoint: number): number;

package/dist/types/grid-index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * How a placed part lets others overlap it, as MapLibre GL JS's `text-overlap` / `icon-overlap`:
+ * `never` overlaps nothing and is overlapped by nothing; `always` overlaps anything; `cooperative`
+ * overlaps `always` and `cooperative` parts, but not `never` ones.
+ */
+export type OverlapMode = 'never' | 'always' | 'cooperative';
+/** Whether a part placed with `mode` may overlap one placed with `placedMode`. */
+export declare function allowsOverlap(mode: OverlapMode, placedMode: OverlapMode): boolean;
+/**
+ * A grid of screen-space boxes and circles for label placement, as MapLibre GL JS's `GridIndex`:
+ * the plane is cut into square cells, each holding the shapes that reach into it, so that a test
+ * compares a shape only with the shapes of the cells it covers. Coordinates are pixels; a shape
+ * that reaches outside the grid is clamped to its edge cells.
+ */
+export declare class GridIndex {
+    readonly width: number;
+    readonly height: number;
+    private readonly cellSize;
+    private readonly columns;
+    private readonly rows;
+    /** Per cell, the indices of the shapes in it. */
+    private readonly cells;
+    /** Per shape: `x1, y1, x2, y2` for a box, `x, y, radius, NaN` for a circle. */
+    private readonly shapes;
+    private readonly modes;
+    /** The query count at which each shape was last compared, so a query compares it once. */
+    private readonly seen;
+    private query;
+    constructor(width: number, height: number, cellSize: number);
+    /** The number of shapes inserted. */
+    get size(): number;
+    /** Adds a box from `x1, y1` to `x2, y2`. */
+    insert(x1: number, y1: number, x2: number, y2: number, mode?: OverlapMode): void;
+    /** Adds a circle. */
+    insertCircle(x: number, y: number, radius: number, mode?: OverlapMode): void;
+    /** Whether a box placed with `mode` would overlap a shape that it may not overlap. */
+    hitTest(x1: number, y1: number, x2: number, y2: number, mode?: OverlapMode): boolean;
+    /** Whether a circle placed with `mode` would overlap a shape that it may not overlap. */
+    hitTestCircle(x: number, y: number, radius: number, mode?: OverlapMode): boolean;
+    /** Whether a box lies at least partly within the grid. */
+    isInside(x1: number, y1: number, x2: number, y2: number): boolean;
+    private add;
+    private test;
+    /** Calls `visit` for each cell the box reaches, until it returns `true`. */
+    private forEachCell;
+    private toCell;
+}

package/dist/types/hillshade-layer.d.ts

@@ -0,0 +1,154 @@
+import type { Layer, LayersList, UpdateParameters } from '@deck.gl/core';
+import { SharedTile2DLayer, SharedTileset2D } from '@deck.gl-community/geo-layers';
+import type { SharedTile2DLayerProps, SharedTileset2DProps } from '@deck.gl-community/geo-layers';
+import type { BasemapLoadOptions, BasemapSource } from "./style-resolver.js";
+/**
+ * `hillshade` style layers over `raster-dem` sources, drawn as MapLibre GL JS draws them.
+ *
+ * MapLibre draws a hillshade in two passes. The first ("prepare") decodes each DEM tile into
+ * elevations and stores the slope of every pixel, scaled for the tile's zoom, in an 8-bit
+ * texture one pixel larger than the tile on every side. The second shades that texture with the
+ * layer's paint. Here the first pass runs on the CPU, with the same arithmetic and the same 8-bit
+ * rounding, and the second in the fragment shader of a `BitmapLayer`, ported from MapLibre's.
+ */
+/** The encodings of a `raster-dem` source. */
+export type DemEncoding = 'mapbox' | 'terrarium' | 'custom';
+/** `[redFactor, greenFactor, blueFactor, baseShift]`: elevation = r·R + g·G + b·B − shift. */
+export type DemUnpackVector = [number, number, number, number];
+/** The elevations of a DEM tile, in meters, row by row from the north-west corner. */
+export type DemTile = {
+    /** Width and height in pixels. */
+    dim: number;
+    elevations: Float32Array;
+};
+/** The unpack vector of a `raster-dem` source, as MapLibre GL JS's `DEMData` chooses it. */
+export declare function getDemUnpackVector(source: BasemapSource): DemUnpackVector;
+/** Decodes the RGBA pixels of a square DEM tile into elevations. */
+export declare function decodeDemTile(pixels: ArrayLike<number>, width: number, height: number, [redFactor, greenFactor, blueFactor, baseShift]: DemUnpackVector): DemTile;
+/**
+ * The DEM tile next to a tile, `dx` and `dy` (each -1, 0 or 1, not both 0) tiles away, or `null`
+ * where it is not loaded.
+ */
+export type DemNeighbors = (dx: number, dy: number) => DemTile | null;
+/**
+ * The slope texture of MapLibre GL JS's hillshade "prepare" pass, `dim + 2` pixels square: the
+ * tile and a one-pixel border, RGBA, with the scaled east-west and north-south slopes in red and
+ * green (128 is flat). Pixels past the tile's edges come from its loaded neighbors, and where a
+ * neighbor is missing, from the tile's nearest edge pixel, as MapLibre fills them.
+ *
+ * `zoom` is the tile's zoom, also where it is scaled up past its source's `maxzoom`. MapLibre
+ * scales the slopes by it, and exaggerates them below zoom 15.
+ */
+export declare function prepareHillshadeTexture(dem: DemTile, zoom: number, getNeighbor?: DemNeighbors): Uint8ClampedArray<ArrayBuffer>;
+/** The most light sources the shader takes. MapLibre takes any number. */
+export declare const MAX_HILLSHADE_LIGHTS = 4;
+/** A hillshade layer's paint, evaluated and ready for the shader (but for the map's bearing). */
+export type HillshadeParameters = {
+    /** `hillshade-method`. */
+    method: number;
+    /** `hillshade-exaggeration`. */
+    exaggeration: number;
+    /** `hillshade-accent-color`, premultiplied RGBA in 0-1. */
+    accent: number[];
+    /** Whether the light turns with the map (`hillshade-illumination-anchor: viewport`). */
+    viewportAnchored: boolean;
+    /** One per light source, at most `MAX_HILLSHADE_LIGHTS`. Directions clockwise from north. */
+    directions: number[];
+    altitudes: number[];
+    /** Premultiplied RGBA in 0-1. */
+    shadows: number[][];
+    highlights: number[][];
+};
+/**
+ * The shader parameters of a hillshade layer's evaluated paint (see `getPaint`), with the
+ * specification's defaults for unset properties. As in MapLibre GL JS, the number of light sources
+ * is the number of `hillshade-highlight-color`s, and the other lists are lengthened to match by
+ * repeating their last value; only `multidirectional` uses more than the first.
+ */
+export declare function getHillshadeParameters(paint: Record<string, unknown>): HillshadeParameters;
+/** The `hillshade` shader module's uniforms. */
+export type HillshadeUniforms = {
+    accent: number[];
+    altitudes: number[];
+    azimuths: number[];
+    shadows: number[];
+    highlights: number[];
+    latRange: [number, number];
+    exaggeration: number;
+    method: number;
+    lightCount: number;
+};
+/**
+ * The shader uniforms of a tile: its parameters, at the map's `bearing` (degrees) for a light
+ * anchored to the viewport, and the tile's latitude range `[north, south]`.
+ */
+export declare function getHillshadeUniforms(parameters: HillshadeParameters, bearing: number, latRange: [number, number]): HillshadeUniforms;
+/**
+ * Fetches and decodes a DEM tile. Colors are read as stored, without color space conversion or
+ * premultiplication, which would change the elevations. An empty response is a tile without data.
+ */
+export declare function loadDemTile(url: string, unpack: DemUnpackVector, { signal, loadOptions }?: {
+    signal?: AbortSignal;
+    loadOptions?: BasemapLoadOptions;
+}): Promise<DemTile | null>;
+/**
+ * Creates the tileset of a `raster-dem` source: each tile is fetched and decoded once, and shared
+ * by every `HillshadeTileLayer` drawn from it, as the tiles of a vector source are shared by its
+ * style runs. `tilesetProps` are the source's tile pyramid (see `getTilePyramidProps`).
+ */
+export declare function createSharedDemTileset(source: BasemapSource, loadOptions: BasemapLoadOptions | undefined, tilesetProps?: Partial<SharedTileset2DProps<DemTile | null>>): SharedTileset2D<DemTile | null>;
+/**
+ * A tileset shared by the `HillshadeTileLayer`s of one `raster-dem` source, finalized when the
+ * last of them is. `BasemapLayer` owns its sources' tilesets itself; this is for the layers that
+ * `getBasemapLayers` creates without it.
+ */
+export type DemTilesetOwner = {
+    tileset: SharedTileset2D;
+    consumers: Set<object>;
+};
+/** Props of a `HillshadeTileLayer`. */
+export type HillshadeTileLayerProps = SharedTile2DLayerProps<DemTile | null> & {
+    hillshadeParameters: HillshadeParameters;
+    /** Extra props of every tile's bitmap layer, such as `parameters`. */
+    hillshadeSubLayerProps?: Record<string, unknown>;
+    /** The owner of a shared `data` tileset that the layer releases when finalized. */
+    demTilesetOwner?: DemTilesetOwner | null;
+};
+/**
+ * The tiles of a `raster-dem` source, shaded by one `hillshade` style layer. The decoded tiles
+ * come from the source's tileset, shared with the source's other hillshade layers (see
+ * `createSharedDemTileset`); the slopes and the shading are the layer's own. Each tile's slopes are
+ * prepared from its elevations and those of its loaded neighbors, so that tiles join without
+ * seams. Draws nothing on WebGPU: the shader is GLSL.
+ */
+export declare class HillshadeTileLayer extends SharedTile2DLayer<DemTile | null, HillshadeTileLayerProps> {
+    static layerName: string;
+    static defaultProps: {
+        hillshadeParameters: {
+            type: string;
+            value: null;
+            compare: boolean;
+        };
+        hillshadeSubLayerProps: {
+            type: string;
+            value: null;
+            compare: boolean;
+        };
+        demTilesetOwner: {
+            type: string;
+            value: null;
+            compare: boolean;
+        };
+    };
+    state: SharedTile2DLayer<DemTile | null>['state'] & {
+        demTilesetOwner?: DemTilesetOwner;
+        /** Stands for this layer among an owner's consumers. */
+        demTilesetConsumer?: object;
+    };
+    updateState(params: UpdateParameters<this>): void;
+    finalizeState(): void;
+    private releaseDemTileset;
+    _onTileLoad(tile: any): void;
+    renderLayers(): Layer | null | LayersList;
+    renderSubLayers(props: any): Layer | null | LayersList;
+}