maplibre-gl 3.2.1 → 3.3.0

package/dist/maplibre-gl.d.ts

@@ -3,7 +3,7 @@
 import Point from '@mapbox/point-geometry';
 import TinySDF from '@mapbox/tiny-sdf';
 import { VectorTileFeature, VectorTileLayer } from '@mapbox/vector-tile';
-import { Color, CompositeExpression, Feature, FeatureFilter, FeatureState, FilterSpecification, Formatted, FormattedSection, GeoJSONSourceSpecification, GlobalProperties, ICanonicalTileID, IMercatorCoordinate, ImageSourceSpecification, InterpolationType, LayerSpecification, LightSpecification, Padding, PromoteIdSpecification, PropertyValueSpecification, RasterDEMSourceSpecification, RasterSourceSpecification, ResolvedImage, SourceExpression, SourceSpecification, SpriteSpecification, StylePropertyExpression, StylePropertySpecification, StyleSpecification, TerrainSpecification, TransitionSpecification, VectorSourceSpecification, VideoSourceSpecification } from '@maplibre/maplibre-gl-style-spec';
+import { Color, CompositeExpression, Feature, FeatureFilter, FeatureState, FilterSpecification, Formatted, FormattedSection, GeoJSONSourceSpecification, GlobalProperties, ICanonicalTileID, IMercatorCoordinate, ImageSourceSpecification, InterpolationType, LayerSpecification, LightSpecification, Padding, PromoteIdSpecification, PropertyValueSpecification, RasterDEMSourceSpecification, RasterSourceSpecification, ResolvedImage, SourceExpression, SourceSpecification, SpriteSpecification, StylePropertyExpression, StylePropertySpecification, StyleSpecification, TerrainSpecification, TransitionSpecification, VariableAnchorOffsetCollection, VectorSourceSpecification, VideoSourceSpecification } from '@maplibre/maplibre-gl-style-spec';
 import { mat2, mat4, vec4 } from 'gl-matrix';
 import KDBush from 'kdbush';
 import { PotpackBox } from 'potpack';
@@ -75,6 +75,10 @@ export type RequestParameters = {
 	 * If `true`, Resource Timing API information will be collected for these transformed requests and returned in a resourceTiming property of relevant data events.
 	 */
 	collectResourceTiming?: boolean;
+	/**
+	 * Parameters supported only by browser fetch API. Property of the Request interface contains the cache mode of the request. It controls how the request will interact with the browser's HTTP cache. (https://developer.mozilla.org/en-US/docs/Web/API/Request/cache)
+	 */
+	cache?: RequestCache;
 };
 /**
  * The response callback used in various places
@@ -426,6 +430,7 @@ export type CrossFaded<T> = {
 	from: T;
 };
 /**
+ * @internal
  *  Implementations of the `Property` interface:
  *
  *  * Hold metadata about a property that's independent of any specific value: stuff like the type of the value,
@@ -504,6 +509,7 @@ export declare class Layout<Props> {
 		[K in keyof Props]: PropertyValue<any, PossiblyEvaluatedPropertyValue<any>>;
 	};
 	constructor(properties: Properties<Props>);
+	hasValue<S extends keyof Props>(name: S): boolean;
 	getValue<S extends keyof Props>(name: S): any;
 	setValue<S extends keyof Props>(name: S, value: any): void;
 	serialize(): any;
@@ -611,6 +617,7 @@ declare const viewTypes: {
 	Float32: Float32ArrayConstructor;
 };
 /**
+ * @internal
  * A view type size
  */
 export type ViewType = keyof typeof viewTypes;
@@ -628,6 +635,7 @@ export declare class Struct {
 	constructor(structArray: StructArray, index: number);
 }
 /**
+ * @internal
  * A struct array memeber
  */
 export type StructArrayMember = {
@@ -784,7 +792,7 @@ export declare class StructArrayLayout2i2ui3ul3ui2f3ub1ul1i48 extends StructArra
 	emplaceBack(v0: number, v1: number, v2: number, v3: number, v4: number, v5: number, v6: number, v7: number, v8: number, v9: number, v10: number, v11: number, v12: number, v13: number, v14: number, v15: number, v16: number): number;
 	emplace(i: number, v0: number, v1: number, v2: number, v3: number, v4: number, v5: number, v6: number, v7: number, v8: number, v9: number, v10: number, v11: number, v12: number, v13: number, v14: number, v15: number, v16: number): number;
 }
-export declare class StructArrayLayout8i15ui1ul4f68 extends StructArray {
+export declare class StructArrayLayout8i15ui1ul2f2ui64 extends StructArray {
 	uint8: Uint8Array;
 	int16: Int16Array;
 	uint16: Uint16Array;
@@ -801,6 +809,14 @@ export declare class StructArrayLayout1f4 extends StructArray {
 	emplaceBack(v0: number): number;
 	emplace(i: number, v0: number): number;
 }
+export declare class StructArrayLayout1ui2f12 extends StructArray {
+	uint8: Uint8Array;
+	uint16: Uint16Array;
+	float32: Float32Array;
+	_refreshViews(): void;
+	emplaceBack(v0: number, v1: number, v2: number): number;
+	emplace(i: number, v0: number, v1: number, v2: number): number;
+}
 export declare class StructArrayLayout1ul2ui8 extends StructArray {
 	uint8: Uint8Array;
 	uint32: Uint32Array;
@@ -901,12 +917,12 @@ export declare class SymbolInstanceStruct extends Struct {
 	get crossTileID(): number;
 	set crossTileID(x: number);
 	get textBoxScale(): number;
-	get textOffset0(): number;
-	get textOffset1(): number;
 	get collisionCircleDiameter(): number;
+	get textAnchorOffsetStartIndex(): number;
+	get textAnchorOffsetEndIndex(): number;
 }
 export type SymbolInstance = SymbolInstanceStruct;
-export declare class SymbolInstanceArray extends StructArrayLayout8i15ui1ul4f68 {
+export declare class SymbolInstanceArray extends StructArrayLayout8i15ui1ul2f2ui64 {
 	/**
 	 * Return the SymbolInstanceStruct at the given location in the array.
 	 * @param index The index of the element.
@@ -921,6 +937,20 @@ export declare class SymbolLineVertexArray extends StructArrayLayout3i6 {
 	gety(index: number): number;
 	gettileUnitDistanceFromAnchor(index: number): number;
 }
+export declare class TextAnchorOffsetStruct extends Struct {
+	_structArray: TextAnchorOffsetArray;
+	get textAnchor(): number;
+	get textOffset0(): number;
+	get textOffset1(): number;
+}
+export type TextAnchorOffset = TextAnchorOffsetStruct;
+export declare class TextAnchorOffsetArray extends StructArrayLayout1ui2f12 {
+	/**
+	 * Return the TextAnchorOffsetStruct at the given location in the array.
+	 * @param index The index of the element.
+	 */
+	get(index: number): TextAnchorOffsetStruct;
+}
 export declare class FeatureIndexStruct extends Struct {
 	_structArray: FeatureIndexArray;
 	get featureIndex(): number;
@@ -1375,6 +1405,7 @@ export declare class UniformMatrix4f extends Uniform<mat4> {
 	set(v: mat4): void;
 }
 /**
+ * @internal
  * A uniform bindings
  */
 export type UniformBindings = {
@@ -1661,6 +1692,7 @@ export type GlyphMetrics = {
 	advance: number;
 };
 /**
+ * @internal
  * A style glyph type
  */
 export type StyleGlyph = {
@@ -2278,6 +2310,7 @@ export declare class DEMData {
 	backfillBorder(borderTile: DEMData, dx: number, dy: number): void;
 }
 /**
+ * @internal
  * The worker tile's result type
  */
 export type WorkerTileResult = {
@@ -2399,9 +2432,7 @@ export declare class ImageSource extends Evented implements Source {
 	boundsSegments: SegmentVector;
 	_loaded: boolean;
 	_request: Cancelable;
-	/**
-	 * @hidden
-	 */
+	/** @internal */
 	constructor(id: string, options: ImageSourceSpecification | VideoSourceSpecification | CanvasSourceSpecification, dispatcher: Dispatcher, eventedParent: Evented);
 	load: (newCoordinates?: Coordinates, successCallback?: () => void) => void;
 	loaded(): boolean;
@@ -2485,9 +2516,7 @@ export declare class CanvasSource extends ImageSource {
 	 */
 	pause: () => void;
 	_playing: boolean;
-	/**
-	 * @hidden
-	 */
+	/** @internal */
 	constructor(id: string, options: CanvasSourceSpecification, dispatcher: Dispatcher, eventedParent: Evented);
 	load: () => void;
 	/**
@@ -2773,6 +2802,7 @@ export type SymbolLayoutProps = {
 	"text-justify": DataDrivenProperty<"auto" | "left" | "center" | "right">;
 	"text-radial-offset": DataDrivenProperty<number>;
 	"text-variable-anchor": DataConstantProperty<Array<"center" | "left" | "right" | "top" | "bottom" | "top-left" | "top-right" | "bottom-left" | "bottom-right">>;
+	"text-variable-anchor-offset": DataDrivenProperty<VariableAnchorOffsetCollection>;
 	"text-anchor": DataDrivenProperty<"center" | "left" | "right" | "top" | "bottom" | "top-left" | "top-right" | "bottom-left" | "bottom-right">;
 	"text-max-angle": DataConstantProperty<number>;
 	"text-writing-mode": DataConstantProperty<Array<"horizontal" | "vertical">>;
@@ -2829,6 +2859,7 @@ export type SymbolLayoutPropsPossiblyEvaluated = {
 	"text-justify": PossiblyEvaluatedPropertyValue<"auto" | "left" | "center" | "right">;
 	"text-radial-offset": PossiblyEvaluatedPropertyValue<number>;
 	"text-variable-anchor": Array<"center" | "left" | "right" | "top" | "bottom" | "top-left" | "top-right" | "bottom-left" | "bottom-right">;
+	"text-variable-anchor-offset": PossiblyEvaluatedPropertyValue<VariableAnchorOffsetCollection>;
 	"text-anchor": PossiblyEvaluatedPropertyValue<"center" | "left" | "right" | "top" | "bottom" | "top-left" | "top-right" | "bottom-left" | "bottom-right">;
 	"text-max-angle": number;
 	"text-writing-mode": Array<"horizontal" | "vertical">;
@@ -3052,6 +3083,7 @@ export declare class SymbolBucket implements Bucket {
 	lineVertexArray: SymbolLineVertexArray;
 	features: Array<SymbolFeature>;
 	symbolInstances: SymbolInstanceArray;
+	textAnchorOffsets: TextAnchorOffsetArray;
 	collisionArrays: Array<CollisionArrays>;
 	sortKeyRanges: Array<SortKeyRange>;
 	pixelRatio: number;
@@ -3282,20 +3314,46 @@ export declare class RenderToTexture {
 	painter: Painter;
 	terrain: Terrain;
 	pool: RenderPool;
+	/**
+	 * coordsDescendingInv contains a list of all tiles which should be rendered for one render-to-texture tile
+	 * e.g. render 4 raster-tiles with size 256px to the 512px render-to-texture tile
+	 */
 	_coordsDescendingInv: {
 		[_: string]: {
 			[_: string]: Array<OverscaledTileID>;
 		};
 	};
+	/**
+	 * create a string representation of all to tiles rendered to render-to-texture tiles
+	 * this string representation is used to check if tile should be re-rendered.
+	 */
 	_coordsDescendingInvStr: {
 		[_: string]: {
 			[_: string]: string;
 		};
 	};
+	/**
+	 * store for render-stacks
+	 * a render stack is a set of layers which should be rendered into one texture
+	 * every stylesheet can have multiple stacks. A new stack is created if layers which should
+	 * not rendered to texture sit inbetween layers which should rendered to texture. e.g. hillshading or symbols
+	 */
 	_stacks: Array<Array<string>>;
+	/**
+	 * remember the previous processed layer to check if a new stack is needed
+	 */
 	_prevType: string;
+	/**
+	 * a list of tiles that can potentially rendered
+	 */
 	_renderableTiles: Array<Tile>;
+	/**
+	 * a list of tiles that should be rendered to screen in the next render-call
+	 */
 	_rttTiles: Array<Tile>;
+	/**
+	 * a list of all layer-ids which should be rendered
+	 */
 	_renderableLayerIds: Array<string>;
 	constructor(painter: Painter, terrain: Terrain);
 	destruct(): void;
@@ -3499,6 +3557,7 @@ export declare class TerrainSourceCache extends Evented {
 	tilesAfterTime(time?: number): Array<Tile>;
 }
 /**
+ * @internal
  * A terrain GPU related object
  */
 export type TerrainData = {
@@ -3513,6 +3572,7 @@ export type TerrainData = {
 	tile: Tile;
 };
 /**
+ * @internal
  * A terrain mesh object
  */
 export type TerrainMesh = {
@@ -4265,6 +4325,7 @@ export declare class VertexArrayObject {
 	destroy(): void;
 }
 /**
+ * @internal
  * A single segment of a vector
  */
 export type Segment = {
@@ -5092,7 +5153,18 @@ export declare class CollisionIndex {
 	isInsideGrid(x1: number, y1: number, x2: number, y2: number): boolean;
 	getViewportMatrix(): mat4;
 }
-export type TextAnchor = "center" | "left" | "right" | "top" | "bottom" | "top-left" | "top-right" | "bottom-left" | "bottom-right";
+declare enum TextAnchorEnum {
+	"center" = 1,
+	"left" = 2,
+	"right" = 3,
+	"top" = 4,
+	"bottom" = 5,
+	"top-left" = 6,
+	"top-right" = 7,
+	"bottom-left" = 8,
+	"bottom-right" = 9
+}
+export type TextAnchor = keyof typeof TextAnchorEnum;
 export declare class OpacityState {
 	opacity: number;
 	placed: boolean;
@@ -5205,7 +5277,7 @@ export declare class Placement {
 	};
 	constructor(transform: Transform, terrain: Terrain, fadeDuration: number, crossSourceCollisions: boolean, prevPlacement?: Placement);
 	getBucketParts(results: Array<BucketPart>, styleLayer: StyleLayer, tile: Tile, sortAcrossTiles: boolean): void;
-	attemptAnchorPlacement(anchor: TextAnchor, textBox: SingleCollisionBox, width: number, height: number, textBoxScale: number, rotateWithMap: boolean, pitchWithMap: boolean, textPixelRatio: number, posMatrix: mat4, collisionGroup: CollisionGroup, textOverlapMode: OverlapMode, symbolInstance: SymbolInstance, bucket: SymbolBucket, orientation: number, iconBox?: SingleCollisionBox | null, getElevation?: (x: number, y: number) => number): {
+	attemptAnchorPlacement(textAnchorOffset: TextAnchorOffset, textBox: SingleCollisionBox, width: number, height: number, textBoxScale: number, rotateWithMap: boolean, pitchWithMap: boolean, textPixelRatio: number, posMatrix: mat4, collisionGroup: CollisionGroup, textOverlapMode: OverlapMode, symbolInstance: SymbolInstance, bucket: SymbolBucket, orientation: number, iconBox?: SingleCollisionBox | null, getElevation?: (x: number, y: number) => number): {
 		shift: Point;
 		placedGlyphBoxes: {
 			box: Array<number>;
@@ -5490,6 +5562,7 @@ export declare class Style extends Evented {
 	hasTransitions(): boolean;
 	_checkLoaded(): void;
 	/**
+	 * @internal
 	 * Apply queued style updates in a batch and recalculate zoom-dependent paint properties.
 	 */
 	update(parameters: EvaluationParameters): void;
@@ -5794,9 +5867,7 @@ export declare class DragPanHandler {
 	_mousePan: MousePanHandler;
 	_touchPan: TouchPanHandler;
 	_inertiaOptions: DragPanOptions | boolean;
-	/**
-	 * @hidden
-	*/
+	/** @internal */
 	constructor(el: HTMLElement, mousePan: MousePanHandler, touchPan: TouchPanHandler);
 	/**
 	 * Enables the "drag to pan" interaction.
@@ -6254,30 +6325,30 @@ declare abstract class Camera extends Evented {
 	_onEaseEnd: (easeId?: string) => void;
 	_easeFrameId: TaskID;
 	/**
-	 * @hidden
+	 * @internal
 	 * holds the geographical coordinate of the target
 	 */
 	_elevationCenter: LngLat;
 	/**
-	 * @hidden
+	 * @internal
 	 * holds the targ altitude value, = center elevation of the target.
 	 * This value may changes during flight, because new terrain-tiles loads during flight.
 	 */
 	_elevationTarget: number;
 	/**
-	 * @hidden
+	 * @internal
 	 * holds the start altitude value, = center elevation before animation begins
 	 * this value will recalculated during flight in respect of changing _elevationTarget values,
 	 * so the linear interpolation between start and target keeps smooth and without jumps.
 	 */
 	_elevationStart: number;
 	/**
-	 * @hidden
+	 * @internal
 	 * Saves the current state of the elevation freeze - this is used during map movement to prevent "rocky" camera movement.
 	 */
 	_elevationFreeze: boolean;
 	/**
-	 * @hidden
+	 * @internal
 	 * Used to track accumulated changes during continuous interaction
 	 */
 	_requestedCameraState?: Transform;
@@ -6549,6 +6620,7 @@ declare abstract class Camera extends Evented {
 	 */
 	cameraForBounds(bounds: LngLatBoundsLike, options?: CameraForBoundsOptions): CenterZoomBearing;
 	/**
+	 * @internal
 	 * Calculate the center of these two points in the viewport and use
 	 * the highest zoom level up to and including `Map#getMaxZoom()` that fits
 	 * the points in the viewport at the specified bearing.
@@ -6558,7 +6630,6 @@ declare abstract class Camera extends Evented {
 	 * @param options - the camera options
 	 * @returns If map is able to fit to provided bounds, returns `center`, `zoom`, and `bearing`.
 	 *      If map is unable to fit, method will warn and return undefined.
-	 * @hidden
 	 * @example
 	 * ```ts
 	 * let p0 = [-79, 43];
@@ -6680,17 +6751,17 @@ declare abstract class Camera extends Evented {
 	_updateElevation(k: number): void;
 	_finalizeElevation(): void;
 	/**
+	 * @internal
 	 * Called when the camera is about to be manipulated.
 	 * If `transformCameraUpdate` is specified, a copy of the current transform is created to track the accumulated changes.
 	 * This underlying transform represents the "desired state" proposed by input handlers / animations / UI controls.
 	 * It may differ from the state used for rendering (`this.transform`).
-	 * @hidden
 	 * @returns Transform to apply changes to
 	 */
 	_getTransformForUpdate(): Transform;
 	/**
+	 * @internal
 	 * Called after the camera is done being manipulated.
-	 * @hidden
 	 * @param tr - the requested camera end state
 	 * Call `transformCameraUpdate` if present, and then apply the "approved" changes.
 	 */
@@ -7438,9 +7509,7 @@ declare abstract class TwoFingersTouchHandler implements Handler {
 	_vector: Point;
 	_startVector: Point;
 	_aroundCenter: boolean;
-	/**
-	 * @hidden
-	 */
+	/** @internal */
 	constructor();
 	reset(): void;
 	abstract _start(points: [
@@ -7571,9 +7640,7 @@ export declare class ScrollZoomHandler implements Handler {
 	_triggerRenderFrame: () => void;
 	_defaultZoomRate: number;
 	_wheelZoomRate: number;
-	/**
-	 * @hidden
-	 */
+	/** @internal */
 	constructor(map: Map, triggerRenderFrame: () => void);
 	/**
 	 * Set the zoom rate of a trackpad
@@ -7646,9 +7713,7 @@ export declare class BoxZoomHandler implements Handler {
 	_lastPos: Point;
 	_box: HTMLElement;
 	_clickTolerance: number;
-	/**
-	 * @hidden
-	 */
+	/** @internal */
 	constructor(map: Map, options: {
 		clickTolerance: number;
 	});
@@ -7702,9 +7767,7 @@ export declare class DragRotateHandler {
 	_mouseRotate: MouseRotateHandler;
 	_mousePitch: MousePitchHandler;
 	_pitchWithRotate: boolean;
-	/**
-	 * @hidden
-	*/
+	/** @internal */
 	constructor(options: DragRotateHandlerOptions, mouseRotate: MouseRotateHandler, mousePitch: MousePitchHandler);
 	/**
 	 * Enables the "drag to rotate" interaction.
@@ -7745,9 +7808,7 @@ export declare class KeyboardHandler implements Handler {
 	_bearingStep: number;
 	_pitchStep: number;
 	_rotationDisabled: boolean;
-	/**
-	* @hidden
-	*/
+	/** @internal */
 	constructor(map: Map);
 	reset(): void;
 	keydown(e: KeyboardEvent): {
@@ -7812,9 +7873,7 @@ export declare class ClickZoomHandler implements Handler {
 	_tr: TransformProvider;
 	_enabled: boolean;
 	_active: boolean;
-	/**
-	 * @hidden
-	*/
+	/** @internal */
 	constructor(map: Map);
 	reset(): void;
 	dblclick(e: MouseEvent, point: Point): {
@@ -7878,9 +7937,7 @@ export declare class TapZoomHandler implements Handler {
 export declare class DoubleClickZoomHandler {
 	_clickZoom: ClickZoomHandler;
 	_tapZoom: TapZoomHandler;
-	/**
-	 * @hidden
-	*/
+	/** @internal */
 	constructor(clickZoom: ClickZoomHandler, TapZoom: TapZoomHandler);
 	/**
 	 * Enables the "double click to zoom" interaction.
@@ -7941,9 +7998,7 @@ export declare class TwoFingersTouchZoomRotateHandler {
 	_tapDragZoom: TapDragZoomHandler;
 	_rotationDisabled: boolean;
 	_enabled: boolean;
-	/**
-	 * @hidden
-	*/
+	/** @internal */
 	constructor(el: HTMLElement, touchZoom: TwoFingersTouchZoomHandler, touchRotate: TwoFingersTouchRotateHandler, tapDragZoom: TapDragZoomHandler);
 	/**
 	 * Enables the "pinch to rotate and zoom" interaction.
@@ -8420,7 +8475,7 @@ export declare class Map extends Camera {
 	];
 	_terrainDataCallback: (e: MapStyleDataEvent | MapSourceDataEvent) => void;
 	/**
-	 * @hidden
+	 * @internal
 	 * image queue throttling handle. To be used later when clean up
 	 */
 	_imageQueueHandle: number;
@@ -8467,9 +8522,9 @@ export declare class Map extends Camera {
 	touchPitch: TwoFingersTouchPitchHandler;
 	constructor(options: MapOptions);
 	/**
+	 * @internal
 	 * Returns a unique number for this map instance which is used for the MapLoadEvent
 	 * to make sure we only fire one event per instantiated map object.
-	 * @hidden
 	 * @returns the uniq map ID
 	 */
 	_getMapId(): number;
@@ -8548,9 +8603,9 @@ export declare class Map extends Camera {
 	 */
 	resize(eventData?: any): Map;
 	/**
+	 * @internal
 	 * Return the map's pixel ratio eventually scaled down to respect maxCanvasSize.
 	 * Internally you should use this and not getPixelRatio().
-	 * @hidden
 	 */
 	_getClampedPixelRatio(width: number, height: number): number;
 	/**
@@ -9958,23 +10013,25 @@ export declare class Map extends Camera {
 	 */
 	loaded(): boolean;
 	/**
+	 * @internal
 	 * Update this map's style and sources, and re-render the map.
 	 *
-	 * @hidden
 	 * @param updateStyle - mark the map's style for reprocessing as
 	 * well as its sources
 	 * @returns `this`
 	 */
 	_update(updateStyle?: boolean): this;
 	/**
+	 * @internal
 	 * Request that the given callback be executed during the next render
 	 * frame.  Schedule a render frame if one is not already scheduled.
-	 * @hidden
+	 *
 	 * @returns An id that can be used to cancel the callback
 	 */
 	_requestRenderFrame(callback: () => void): TaskID;
 	_cancelRenderFrame(id: TaskID): void;
 	/**
+	 * @internal
 	 * Call when a (re-)render of the map is required:
 	 * - The style has changed (`setPaintProperty()`, etc.)
 	 * - Source data has changed (e.g. tiles have finished loading)
@@ -9982,7 +10039,6 @@ export declare class Map extends Camera {
 	 * - A transition is in progress
 	 *
 	 * @param paintStartTimeStamp - The time when the animation frame began executing.
-	 * @hidden
 	 *
 	 * @returns `this`
 	 */
@@ -11081,9 +11137,7 @@ export declare class GeoJSONSource extends Evented implements Source {
 	_pendingLoads: number;
 	_collectResourceTiming: boolean;
 	_removed: boolean;
-	/**
-	 * @hidden
-	 */
+	/** @internal */
 	constructor(id: string, options: GeoJSONSourceOptions, dispatcher: Dispatcher, eventedParent: Evented);
 	load: () => void;
 	onAdd(map: Map): void;