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

package/dist/types/index.d.ts

@@ -0,0 +1,9 @@
+/** Runtime exports for `@deck.gl-community/basemap-layers`. */
+export { BasemapLayer } from "./basemap-layer.js";
+export { createDemTileset, getBasemapLayers, getGlobeBaseLayers, getGlobeTopLayers } from "./globe-layers.js";
+export { getSpriteIconMapping, getSpriteSources, loadSpriteAtlases } from "./sprite.js";
+export type { SpriteAtlas, SpriteIconMappingEntry, SpriteSource } from "./sprite.js";
+export { getLabelFont } from "./text-font.js";
+export type { LabelFont, LabelFontFamily } from "./text-font.js";
+export { GlyphStore } from "./glyph-store.js";
+export type { GlyphStoreOptions } from "./glyph-store.js";

package/dist/types/is-globe-viewport.d.ts

@@ -0,0 +1,2 @@
+/** Detect a globe projection, including across copies of deck.gl. */
+export declare function isGlobeViewport(viewport: unknown): boolean;

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

@@ -0,0 +1,18 @@
+import type { TextLayerProps } from '@deck.gl/layers';
+type GetFontRenderer = NonNullable<TextLayerProps['_getFontRenderer']>;
+type FontRenderer = ReturnType<GetFontRenderer>;
+type FontSettings = Parameters<GetFontRenderer>[0];
+/**
+ * The signed distance field font renderer of label text: `TextLayer`'s own, with the same TinySDF,
+ * but keeping the part of a glyph left of its origin. `TextLayer` takes a glyph's origin at the left
+ * edge of the distance field TinySDF draws: TinySDF 2.0 cuts off the left of `f`, `j`, `y` and other
+ * italic glyphs that reach behind their origin, and TinySDF 2.2 and later draw every glyph from the
+ * left edge of its ink (`glyphLeft`), which `TextLayer` then draws off its origin.
+ *
+ * `TextLayer` leaves `fontSettings.buffer` atlas pixels before each glyph's origin, so the distance
+ * field left of a glyph is cut by the length of its overhang: a glyph keeps all its ink, and a halo
+ * reaches `buffer` minus the overhang atlas pixels left of it (9 of 18 for Noto Sans Italic `j` in
+ * a 64 px atlas, 1.7 px on 12 px text).
+ */
+export declare function getLabelFontRenderer(settings: FontSettings): FontRenderer;
+export {};

package/dist/types/label-placement.d.ts

@@ -0,0 +1,247 @@
+import { LayerExtension } from '@deck.gl/core';
+import type { Layer, Viewport } from '@deck.gl/core';
+import type { Device, Texture } from '@luma.gl/core';
+import { GridIndex, type OverlapMode } from "./grid-index.js";
+/**
+ * Pixels around the viewport in which symbols are placed, so that a symbol just outside it still
+ * hides those it would overlap when it comes in: MapLibre GL JS's `viewportPadding`.
+ */
+export declare const PLACEMENT_VIEWPORT_PADDING = 100;
+/**
+ * Milliseconds between two placements while the view keeps changing, as MapLibre GL JS's default
+ * `fadeDuration`. The view the map comes to rest in is always placed.
+ */
+export declare const DEFAULT_PLACEMENT_INTERVAL = 300;
+/**
+ * A symbol part's collision shape in grid pixels (screen pixels moved by
+ * `PLACEMENT_VIEWPORT_PADDING`): a box `[x1, y1, x2, y2]`, or circles `[x, y, radius, ...]` for
+ * text along a line.
+ */
+export type PlacementShape = {
+    box: number[];
+    circles?: undefined;
+} | {
+    circles: number[];
+    box?: undefined;
+};
+/** One symbol to place: the slot its visibility is written to, and its parts' shapes. */
+export type PlacementSymbol = {
+    slot: number;
+    /** `null` when the symbol draws no text. */
+    text: PlacementShape | null;
+    /** `null` when the symbol draws no icon. */
+    icon: PlacementShape | null;
+    /** Hidden whatever its collisions: beyond a globe's horizon. */
+    occluded?: boolean;
+    /**
+     * Its icon is still loading. Unless the icon is optional, the symbol is not placed until it has
+     * loaded, as MapLibre GL JS lays out no symbol until its images have loaded: its text, placed
+     * alone, would hide when the icon arrives and collides.
+     */
+    iconPending?: boolean;
+    /**
+     * With `text-variable-anchor`: the text's shape at each of its anchors, in the order they are
+     * tried, and the slot whose text is drawn at each. `text` is the first one's shape, and `key`
+     * names the symbol across placements, so that it keeps the anchor it was placed at while that
+     * still fits, as in MapLibre GL JS.
+     */
+    textAnchors?: {
+        shapes: PlacementShape[];
+        slots: number[];
+        key: object;
+    };
+};
+/** A symbol style layer's placement rules, from its layout, as MapLibre GL JS reads them. */
+export type SymbolPlacementRules = {
+    textOverlap: OverlapMode;
+    iconOverlap: OverlapMode;
+    textIgnorePlacement: boolean;
+    iconIgnorePlacement: boolean;
+    textOptional: boolean;
+    iconOptional: boolean;
+    /** Whether the layer draws any text, and any icon (MapLibre's `hasTextData`/`hasIconData`). */
+    hasTextData: boolean;
+    hasIconData: boolean;
+};
+/** Visibility bits of a placed symbol. */
+export declare const TEXT_VISIBLE = 1;
+export declare const ICON_VISIBLE = 2;
+/** `placeSymbol` returns the index of the anchor its text is placed at above the visibility bits. */
+export declare const ANCHOR_SHIFT = 2;
+/**
+ * Places one symbol in `grid`, as MapLibre GL JS's `Placement.placeLayerBucketPart` places a
+ * symbol instance: each part is placeable where it lies in the grid and overlaps nothing it may not
+ * overlap; a part that is not optional is placed only with the other part; placed parts are added
+ * to the grid unless they ignore placement. Text with variable anchors is placed at the first of
+ * them where it fits (see `getTextAnchor`); its icon stays where it is. Returns the visibility bits
+ * (`TEXT_VISIBLE`, `ICON_VISIBLE`), and the index of the text's anchor shifted by `ANCHOR_SHIFT`.
+ * A part that always overlaps, of a symbol whose other part does too or is optional or absent, is
+ * shown even outside the grid (MapLibre's `alwaysShowText`/`Icon`).
+ */
+export declare function placeSymbol(grid: GridIndex, symbol: PlacementSymbol, rules: SymbolPlacementRules, previousAnchor?: number): number;
+/** A label layer that takes part in placement (`MVTLabelLayer`). */
+export interface PlacementLayer {
+    /**
+     * The layer's place in the style: layers with a higher order are placed first, as MapLibre GL
+     * JS places style layers from the top down.
+     */
+    getPlacementOrder(): number;
+    /** A value that changes whenever what the layer would place changes, other than the view. */
+    getPlacementRevision(): number;
+    /**
+     * A value that changes whenever the layer's symbols take other slots from its slot base, as when
+     * its rows change: the placement made before then holds the visibility of other symbols in
+     * those slots, or of none, so the layer is placed again at once, whether or not the view moves.
+     */
+    getPlacementSlotRevision(): number;
+    /** The number of slots the layer's symbols use, `0..count-1` from its slot base. */
+    getPlacementSlotCount(): number;
+    /**
+     * Whether the layer is drawn in `viewport`: a hidden layer, or one of another view, has no say
+     * in what is placed there.
+     */
+    isDrawnIn(viewport: Viewport): boolean;
+    /** Appends the layer's symbols in its placement order, for `viewport`, to `out`. */
+    getPlacementSymbols(viewport: Viewport, slotBase: number, out: PlacementSymbol[]): SymbolPlacementRules | null;
+    /** Requests another frame, while a placement waits for the throttle. */
+    setNeedsRedraw(): void;
+    /**
+     * The deck layer the layer is drawn under (its topmost parent, or itself), and the deck's layers
+     * in draw order. Of two layers under different deck layers, the one under the later deck layer
+     * is placed first, as MapLibre GL JS places the layers drawn over others first; the placement
+     * order decides only between layers under the same deck layer. Without it, the layer is placed
+     * by its placement order alone, after the layers that give one. Deck layers are told apart by
+     * their ids, which deck.gl keeps when it makes a new instance of a layer.
+     */
+    getPlacementRoot?(): {
+        root: {
+            id: string;
+        };
+        layers: readonly PlacementDeckLayer[];
+    } | null;
+}
+/** What placement reads of a deck's layers (see `PlacementLayer.getPlacementRoot`). */
+export type PlacementDeckLayer = {
+    id: string;
+    parent?: unknown;
+};
+/**
+ * Places the symbols of every registered label layer together, as MapLibre GL JS's `Placement`:
+ * greedily, style layers from the top down, each against the symbols placed before it in a grid
+ * over the viewport. Each symbol's text and icon visibility is written to a texture that the label
+ * sublayers read (`LabelPlacementExtension`), one per viewport id. Placement runs from the label
+ * sublayers' draw: at most every `interval` ms while the view keeps moving, and at once when the
+ * view is at rest and the labels or the view changed since the last placement.
+ */
+export declare class LabelPlacement {
+    interval: number;
+    /** Each layer's slots, and the allocation that gave them (see `getSlotLayout`). */
+    private readonly layers;
+    private readonly views;
+    private capacity;
+    /** Counts the slot allocations made. */
+    private allocations;
+    /** Changes when a layer joins, leaves or moves its slots. */
+    private version;
+    private readonly symbols;
+    /** Each layer's state at the frame being placed, in registration order (see `getRevision`). */
+    private readonly states;
+    /** The index of each top-level deck layer, by id, in the deck's layers last read. */
+    private rootIndices;
+    /**
+     * Adds a layer, or updates its slot count; returns its slot base. A layer that needs more slots
+     * than it has takes the first free ones that are enough, and gives up its own. No other layer
+     * moves: each draws from the slots it read at its last update, until it updates again.
+     */
+    register(layer: PlacementLayer): number;
+    unregister(layer: PlacementLayer): void;
+    /** The slot base of a registered layer, or -1. */
+    getSlotBase(layer: PlacementLayer): number;
+    /**
+     * The first `count` slots that no layer but `growing` uses, past the last layer's slots when no
+     * gap between them is enough. The textures grow to hold them, keeping every slot's visibility.
+     */
+    private allocate;
+    private getView;
+    /**
+     * The visibility texture for `viewport`, placing first when a placement is due. `frame` names the
+     * frame being drawn (deck.gl's timeline time; each call is a frame of its own without it): the
+     * label sublayers of a frame all draw with the placement decided at its first one. Picking passes
+     * read the last placement and never place.
+     */
+    prepare(device: Device, viewport: Viewport, isPicking: boolean, now: number, frame?: number): Texture;
+    /**
+     * A value that changes whenever what would be placed in `viewport` changes, other than the view:
+     * a layer joins or leaves, its symbols change, it is drawn in the viewport or no longer is, or
+     * its deck layer moves among the deck's layers. Reads each layer's state for `place`.
+     */
+    private getRevision;
+    /** The index of a layer's deck layer among the deck's layers, or -1. */
+    private getRootIndex;
+    /**
+     * A value that changes whenever a layer's symbols take other slots: the layer is given new ones,
+     * by an allocation of its own (a layer that takes the slots another left has another), or its
+     * rows change.
+     */
+    private getSlotLayout;
+    private getTexture;
+    /** Places every registered layer's symbols for `viewport`. */
+    private place;
+    /**
+     * The layers drawn in the viewport of the last `getRevision`, in the order they are placed: under
+     * the later deck layer first, then by placement order, highest first (see
+     * `PlacementLayer.getPlacementRoot`). Layers that tie keep the order they registered in.
+     */
+    private getPlacementOrder;
+    /** Releases the textures. */
+    destroy(): void;
+}
+/**
+ * Takes a use of the placement shared by the label layers of the deck that `key` names (its layer
+ * manager), made at the first use. Each use is given back with `releaseSharedLabelPlacement`.
+ */
+export declare function acquireSharedLabelPlacement(key: object): LabelPlacement;
+/** Gives back a use of a deck's shared placement, which is released with its last use. */
+export declare function releaseSharedLabelPlacement(key: object | null | undefined): void;
+/** The key of the shared placement of a layer's deck: its layer manager. */
+export declare function getSharedLabelPlacementKey(layer: {
+    context?: unknown;
+}): object;
+/** Props that `LabelPlacementExtension` adds to a label sublayer. */
+export type LabelPlacementExtensionProps = {
+    /** The placement that decides which symbols are drawn; all are drawn without it. */
+    labelPlacement?: LabelPlacement | null;
+    /** The slot of each object; a negative slot is always drawn. */
+    getPlacementSlot?: (object: any, info: {
+        index: number;
+    }) => number;
+    /** Which visibility the sublayer draws by: its symbols' text (0) or icons (1). */
+    placementPart?: 0 | 1;
+};
+/**
+ * Draws a label sublayer's objects only where `labelPlacement` placed their part (text or icon):
+ * each object's slot is an attribute (`getPlacementSlot`), and the vertex shader reads its
+ * visibility from the placement's texture for the viewport being drawn. Added to a composite layer
+ * such as `TextLayer`, it reaches the character and background sublayers, so a hidden label is
+ * neither drawn nor picked. WebGL only.
+ */
+export declare class LabelPlacementExtension extends LayerExtension {
+    static extensionName: string;
+    static defaultProps: {
+        labelPlacement: {
+            type: string;
+            value: null;
+            compare: boolean;
+        };
+        getPlacementSlot: {
+            type: string;
+            value: number;
+        };
+        placementPart: number;
+    };
+    isEnabled(layer: Layer): boolean;
+    getShaders(this: Layer<LabelPlacementExtensionProps>, extension: this): any;
+    initializeState(this: Layer<LabelPlacementExtensionProps>, context: any, extension: this): void;
+    updateState(this: Layer<LabelPlacementExtensionProps>, params: any, extension: this): void;
+    draw(this: Layer<LabelPlacementExtensionProps>, params: any, extension: this): void;
+}

package/dist/types/label-text-layer.d.ts

@@ -0,0 +1,231 @@
+import { TextLayer, _MultiIconLayer as MultiIconLayer } from '@deck.gl/layers';
+import type { TextLayerProps } from '@deck.gl/layers';
+import type { Accessor, Attribute, DefaultProps, FilterContext } from '@deck.gl/core';
+import { Buffer } from '@luma.gl/core';
+import type { Texture } from '@luma.gl/core';
+import { SharedTextureSet } from "./shared-texture.js";
+/** `text-justify`: `auto` aligns the lines of a label by its text anchor, as `TextLayer` does. */
+export type LabelTextJustify = 'auto' | 'left' | 'center' | 'right';
+/** Where each character of a label is drawn, as `TextLayer`'s `transformParagraph` returns it. */
+export type ParagraphLayout = {
+    /** Character positions in the row, in font atlas pixels. */
+    x: number[];
+    y: number[];
+    /** Width of each character's row. */
+    rowWidth: number[];
+    /** Width and height of the label box. */
+    size: [number, number];
+};
+type _LabelTextLayerProps<DataT> = {
+    /** Space added after each character but the last of a line, in ems of the text size. */
+    getLetterSpacing?: Accessor<DataT, number>;
+    /** How the lines of a label are aligned within its box. */
+    getTextJustify?: Accessor<DataT, LabelTextJustify>;
+    /**
+     * Where each glyph of a label along a line is drawn in a viewport (see {@link LineGlyphPlacement}),
+     * or null to draw the label straight, turned by `getAngle`. Null for every label draws them all
+     * straight. Its update trigger is `updateTriggers.getLineGlyphs`. WebGL only.
+     */
+    getLineGlyphs?: ((object: DataT, viewport: any) => Float32Array | null) | null;
+    /**
+     * What `getLineGlyphs` depends on in the viewport: the glyphs are placed again when it changes,
+     * as the layer draws.
+     */
+    getLineGlyphKey?: ((viewport: any) => string) | null;
+    /**
+     * Mip levels of the font atlas texture (see `LABEL_ATLAS_MIP_LEVELS`). 1 samples the atlas
+     * without mipmaps, as MapLibre GL JS samples its 24 px glyphs.
+     */
+    atlasMipLevels?: number;
+    /**
+     * Whether the glyph edge is smoothed no more than `fontSettings.smoothing`, which keeps small
+     * text from the 64 px label font atlas crisp. False smooths it as MapLibre GL JS smooths its
+     * 24 px glyphs, which is wider on small text.
+     */
+    edgeGammaCapped?: boolean;
+};
+/**
+ * `getLineGlyphs` of a label: 4 values per character, `dx, dy, angle, mode`. With mode 1 the
+ * character's advance centre is drawn `dx, dy` pixels from the label's position (y down), turned by
+ * `angle` degrees counter-clockwise, and `getPixelOffset` is not added; with mode -1 the label is not
+ * drawn; with mode 0 it is drawn straight.
+ */
+export type LineGlyphPlacement = Float32Array;
+export type LabelTextLayerProps<DataT = unknown> = _LabelTextLayerProps<DataT> & TextLayerProps<DataT>;
+/**
+ * Spaces and justifies the lines of a label laid out by `TextLayer`, as MapLibre shapes text:
+ * `spacing` atlas pixels follow each character of a line but the last, the label box widens to the
+ * widest line, and each line is placed at `justify` across the box (0 left, 0.5 center, 1 right).
+ * `TextLayer` places each line at the text anchor's position, `anchor`, so a line is shifted by
+ * `(justify - anchor)` times the space it leaves in the box. `layout` is returned as is when
+ * neither changes it.
+ */
+export declare function spaceParagraph(layout: ParagraphLayout, text: string, spacing: number, justify: number, anchor: number): ParagraphLayout;
+/** A label's packed character definitions and the inputs they were made from. */
+type CachedIconDefs = {
+    text: string;
+    offsets: number[];
+    iconAtlas: unknown;
+    iconMapping: unknown;
+    defs: Float32Array;
+};
+/** The glyphs along lines of a view other than the one the glyph attribute holds. */
+type ViewLineGlyphs = {
+    /** The `getLineGlyphKey` they were placed for. */
+    key: string;
+    /** The glyph attribute revision they were placed at. */
+    revision: number;
+    values: Float32Array;
+    buffer: Buffer;
+};
+/**
+ * Half the width, in device pixels, over which MapLibre GL JS antialiases the edges of glyphs and
+ * of their halos: its symbol shader's `EDGE_GAMMA` (0.105 / device pixel ratio) of a distance
+ * field that falls by 1/8 per glyph pixel, scaled with the text.
+ */
+export declare const LABEL_EDGE_DEVICE_PIXELS = 0.84;
+/**
+ * How much the view shortens screen y for the labels of a layer, against screen x: the cosine of a
+ * `MapView`'s pitch for labels that lie on the map, which it tilts about screen x, as MapLibre's
+ * `u_gamma_scale`. Billboards face the screen, and other views tilt otherwise (a `FirstPersonView`
+ * measures its pitch from the horizon): their labels are taken as unforeshortened, 1.
+ */
+export declare function getLabelForeshortening(viewport: unknown, billboard: boolean): number;
+/**
+ * The character layer of a `LabelTextLayer`. `TextLayer` packs, for every character of every
+ * label, its place in the font atlas and its offset in the label, whenever the layer's data
+ * changes. The packed values of each label are kept, and reused while its text, character offsets
+ * and font atlas are the same, so the labels a layer held before are not packed again.
+ *
+ * On WebGL it antialiases glyph and halo edges as MapLibre GL JS (see `LABEL_SDF_EDGES`). The
+ * WebGPU shader is `MultiIconLayer`'s.
+ */
+/** @internal Exported for tests. */
+export declare class LabelCharactersLayer extends MultiIconLayer<any> {
+    static layerName: string;
+    static defaultProps: DefaultProps<any>;
+    state: MultiIconLayer<any>['state'] & {
+        /** Each label's packed character definitions, by label object. */
+        iconDefs?: WeakMap<object, CachedIconDefs>;
+        /**
+         * The view whose glyphs along lines the glyph attribute holds, and the `getLineGlyphKey` they
+         * were placed for (null when some rows were placed for another).
+         */
+        lineGlyphView?: {
+            id: string;
+            key: string | null;
+        };
+        /** Glyphs along lines of the other views drawn, by view id, least recently drawn first. */
+        lineGlyphViews?: Map<string, ViewLineGlyphs>;
+        /** Counts the glyph attribute's updates, after which the other views' glyphs are placed again. */
+        lineGlyphRevision?: number;
+    };
+    /** Whether characters can be placed along lines: on WebGL, whose shader this layer extends. */
+    drawsLineGlyphs(): boolean;
+    /** Glyph and halo edges as MapLibre GL JS, then, on WebGL, glyphs along lines. */
+    getShaders(): any;
+    initializeState(): void;
+    updateState(params: any): void;
+    /**
+     * Places the glyphs along lines again before drawing when the view has moved to another zoom or
+     * bearing step (`getLineGlyphKey`). The rows and every other attribute stay as they are. A layer
+     * drawn in several views, as a main map and a minimap, keeps the glyphs of each: the attribute
+     * holds one view's, the others are kept in buffers of their own, bound in their place as each
+     * view is drawn.
+     */
+    draw(params: any): void;
+    /**
+     * The glyphs along lines of view `id`, which the glyph attribute does not hold: kept while its
+     * key and the attribute's rows are the same, placed again and uploaded otherwise.
+     */
+    getViewLineGlyphs(attribute: Attribute, id: string, key: string): ViewLineGlyphs;
+    finalizeState(context: any): void;
+    /** Releases the glyphs along lines kept for views other than the attribute's. */
+    forgetViewLineGlyphs(): void;
+    /** Each character's `getLineGlyphs` values; a constant when no label is placed along a line. */
+    protected calculateInstanceLineGlyphs(attribute: Attribute, { startRow, endRow }: {
+        startRow: number;
+        endRow: number;
+    }): void;
+    /**
+     * Writes the `getLineGlyphs` values of rows `startRow` to `endRow` at the current viewport, into
+     * `output`, laid out as the attribute: by default, its value.
+     */
+    fillLineGlyphs(attribute: Attribute, startRow: number, endRow: number, output?: Float32Array): void;
+    /**
+     * Each character's advance centre in the label, in font atlas pixels, about which a glyph along a
+     * line turns: its offset in the label, less its frame's anchor, plus half its advance.
+     */
+    protected calculateInstanceGlyphCentres(attribute: Attribute, { startRow, endRow }: {
+        startRow: number;
+        endRow: number;
+    }): void;
+    protected calculateInstanceIconDefs(attribute: Attribute, { startRow, endRow }: {
+        startRow: number;
+        endRow: number;
+    }): void;
+}
+/**
+ * Glyph attribute work for benchmarks: rows filled and bytes written from `getLineGlyphs`, and
+ * refreshes of the whole attribute when the view crosses a zoom or bearing step.
+ */
+export declare const LINE_GLYPH_ATTRIBUTE_STATS: {
+    fills: number;
+    bytes: number;
+    refreshes: number;
+};
+/**
+ * A `TextLayer` with MapLibre's `text-letter-spacing` and `text-justify`. Both change where the
+ * characters are drawn and the label box, which the background, and so the collision box, covers.
+ * The box is recomputed when the `getText` (letter spacing) or `getTextAnchor` (justification)
+ * update triggers change.
+ *
+ * It draws its glyphs from a font atlas texture shared with every other label layer of the same
+ * atlas. `TextLayer` hands its glyph layer the atlas canvas, from which deck.gl creates and uploads
+ * a texture per layer: one per label sublayer of every tile.
+ */
+export declare class LabelTextLayer<DataT = any, ExtraPropsT extends {} = {}> extends TextLayer<DataT, ExtraPropsT & Required<_LabelTextLayerProps<DataT>>> {
+    static layerName: string;
+    static defaultProps: DefaultProps<LabelTextLayerProps<unknown>>;
+    state: TextLayer<DataT>['state'] & {
+        atlasTextures?: SharedTextureSet;
+        /** The shared texture of the current font atlas, which the glyph layer draws from. */
+        atlasTexture?: Texture;
+        /** Each label's layout, by label object (see `transformParagraph`). */
+        layouts?: WeakMap<object, CachedLayout>;
+    };
+    initializeState(): void;
+    renderLayers(): any;
+    /** Its characters are drawn by a `LabelCharactersLayer`. */
+    getSubLayerClass(subLayerId: string, DefaultLayerClass: any): any;
+    /**
+     * The glyph layer's props, with the shared texture in place of the atlas canvas, and the row's
+     * placement slot (see `LabelPlacementExtension`).
+     */
+    getSubLayerProps(sublayerProps?: any): any;
+    /**
+     * A transparent background without a border draws nothing on screen: it only marks the labels in
+     * the collision map and the picking buffer. It is left out of the screen pass, which saves a draw
+     * per label layer and frame.
+     */
+    filterSubLayer({ layer, renderPass, isPicking }: FilterContext): boolean;
+    /**
+     * Whether the background box is a constant transparent color without a border, no transition
+     * fades it out, and no highlight colors it.
+     */
+    hasInvisibleBackground(): boolean;
+    finalizeState(context: any): void;
+}
+/** A label's layout and every input it was computed from (see `transformParagraph`). */
+type CachedLayout = {
+    text: string;
+    letterSpacing: number;
+    justify: unknown;
+    anchor: unknown;
+    atlas: unknown;
+    lineHeight: number;
+    wordBreak: unknown;
+    maxWidth: number;
+    layout: ParagraphLayout;
+};
+export {};

package/dist/types/line-blur-extension.d.ts

@@ -0,0 +1,73 @@
+import { LayerExtension } from '@deck.gl/core';
+import type { Layer, UpdateParameters } from '@deck.gl/core';
+import type { ShaderModule } from '@luma.gl/shadertools';
+export type LineBlurExtensionOptions = {
+    /**
+     * Reads `getBlur` per path, from an attribute. Otherwise `getBlur` must be a constant, which a
+     * uniform carries: a `PathLayer` with `PathStyleExtension`'s path dashes and offsets already
+     * uses all 16 vertex attributes that WebGL2 guarantees, and does not link with one more.
+     */
+    perFeature: boolean;
+};
+type LineBlurProps = {
+    blur: number;
+    gapOffset: number;
+    gapSide: number;
+};
+/**
+ * Adds `getBlur` to the `PathLayer`s of a layer drawn with `antialiasing` (for a `GeoJsonLayer`,
+ * `lineAntialiasing`): per path, the CSS pixels over which the edges fade out, as MapLibre GL JS
+ * draws `line-blur`, and, with a blur of 0, every line's antialiasing. MapLibre fades each edge
+ * linearly from the edge, which its antialiasing moves out by half a device pixel, to `blur` plus
+ * one device pixel inside it. On deck.gl's antialiased stroke alone, that fade leaves a line
+ * narrower than a pixel too faint, so lines without an offset (which is measured in widths) are
+ * drawn half a device pixel wider on each side, with their dashes scaled back to the line's width,
+ * and faded from their own edge. The fade follows round caps and joins, as in MapLibre. Other
+ * sublayers, and
+ * layers drawn without `antialiasing`, are left unchanged. WebGL only; on WebGPU lines draw
+ * without blur.
+ *
+ * `blurGapSide` serves the two lines of a `line-gap-width`, drawn with `PathStyleExtension`'s
+ * offsets: 1 or -1, the side of the gap's center that this line is on (as `getLineOffset`'s
+ * `side`), with `blurGapOffset` the CSS pixels of the gap's center from the path (`line-offset`).
+ * The line draws nothing past the gap's center, so that where a blur wider than half the gap makes
+ * the two lines overlap, their fades do not draw over each other. MapLibre draws the gap as one
+ * stroke whose fade is symmetric about its center, so each line draws its half. The default 0
+ * clips nothing, and neither does a path whose gap is 0: its one line is centered on the gap's
+ * center (`getLineOffset`), which the shader tells per path from the offset and width it already
+ * has, so a gap that is 0 at a zoom or for a feature needs no attribute of its own.
+ */
+export declare class LineBlurExtension extends LayerExtension<LineBlurExtensionOptions> {
+    static extensionName: string;
+    static defaultProps: {
+        getBlur: {
+            type: string;
+            value: number;
+        };
+        blurGapSide: number;
+        blurGapOffset: number;
+    };
+    constructor({ perFeature }?: Partial<LineBlurExtensionOptions>);
+    initializeState(this: Layer, context: unknown, extension: this): void;
+    updateState(this: Layer<any>, params: UpdateParameters<Layer<any>>, extension: this): void;
+    getShaders(this: Layer, extension: this): {
+        modules?: undefined;
+        defines?: undefined;
+    } | {
+        modules: ShaderModule<LineBlurProps>[];
+        defines: {
+            LINE_BLUR_PER_FEATURE: boolean;
+        } | {
+            LINE_BLUR_PER_FEATURE?: undefined;
+        };
+    };
+}
+/**
+ * The width to draw each of a gap's two lines with, so that their fades fall where MapLibre's do:
+ * MapLibre draws the two lines as one stroke whose inner edges fade into the gap and whose outer
+ * edges fade inward, each over the same `blur`. Drawing each line `blur` wider, and `blur / 2`
+ * closer to the gap (see `getLineOffset`), turns that into a fade inward from both of the line's
+ * edges. Lines without a gap, or without width, keep their width.
+ */
+export declare function getBlurredLineWidth(width: number, gapWidth: number, blur: number): number;
+export {};

package/dist/types/line-glyphs.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Glyphs of a label along a line, each placed on the line and turned to the segment it lands on,
+ * as MapLibre GL JS's `placeGlyphsAlongLine`, `placeFirstAndLastGlyph` and `placeGlyphAlongLine`
+ * (symbol/projection.ts) place them in the label plane. Here the label plane is the map plane at
+ * the current zoom: the line, measured in pixels at the placement zoom, is scaled about the anchor.
+ *
+ * Coordinates are pixels with y pointing down. Angles returned are counter-clockwise on screen, in
+ * degrees, as deck.gl's `getAngle` takes them.
+ */
+/** A line a label is placed along, and where on it the label's anchor lies. */
+export type LabelLine = {
+    /** The line's vertices, `x, y` pairs in pixels at the placement zoom. */
+    points: ArrayLike<number>;
+    /** The segment the anchor lies on: from vertex `segment` to `segment + 1`. */
+    segment: number;
+    /** The anchor's position along that segment, from 0 to 1. */
+    t: number;
+};
+export type LineGlyphOptions = {
+    /**
+     * Each glyph's advance centre along the label, in pixels at the current zoom, from the anchor
+     * (MapLibre's `glyphOffsetArray` times the font scale).
+     */
+    offsets: ArrayLike<number>;
+    /** The label's `text-offset` in pixels: along the line, and across it (MapLibre's `lineOffset`). */
+    lineOffsetX?: number;
+    lineOffsetY?: number;
+    /** Pixels at the current zoom per pixel of `line.points`. */
+    scale: number;
+    /** Whether the label reads against the line's direction (turned upright). */
+    flip: boolean;
+};
+/** Where each glyph of a label is drawn, from the anchor, and the path its collision follows. */
+export type LineGlyphs = {
+    /** For each glyph: `dx, dy` in pixels from the anchor, and its angle. */
+    glyphs: Float32Array;
+    /**
+     * The path from the first glyph to the last along the line, `x, y` pairs in pixels from the
+     * anchor, as MapLibre builds the collision circles of a label along a line.
+     */
+    path: number[];
+};
+/**
+ * Places each glyph of a label along `line`, as MapLibre GL JS draws text along a line. Returns
+ * null when the first or the last glyph does not fit on the line: MapLibre then hides the label.
+ * `flip` is decided by the caller (see {@link needsFlip}); MapLibre's own flip test is on screen.
+ */
+export declare function placeLineGlyphs(line: LabelLine, options: LineGlyphOptions): LineGlyphs | null;
+/**
+ * MapLibre's `requiresOrientationChange` for horizontal text: whether a label placed unflipped reads
+ * right to left on screen, its first glyph right of its last, on a flat map turned by `bearing`.
+ */
+export declare function needsFlip(unflipped: LineGlyphs, bearing: number): boolean;
+/**
+ * Collision circles along a path on screen, as MapLibre GL JS's `placeCollisionCircles` lays them
+ * out with its `PathInterpolator`: the path's ends inset by a quarter radius, circles at most 2.5
+ * radii apart, and one circle on a path shorter than half a radius (or at the middle of the path
+ * for a radius of 0). Returns `x, y, radius` triples.
+ */
+export declare function getPathCircles(path: ArrayLike<number>, radius: number): number[];