maplibre-gl 3.1.0 → 3.2.0-pre.2

package/src/source/source.ts

@@ -1,47 +1,54 @@
-import {bindAll} from '../util/util';
+import {VectorTileSource} from '../source/vector_tile_source';
+import {RasterTileSource} from '../source/raster_tile_source';
+import {RasterDEMTileSource} from '../source/raster_dem_tile_source';
+import {GeoJSONSource} from '../source/geojson_source';
+import {VideoSource} from '../source/video_source';
+import {ImageSource} from '../source/image_source';
+import {CanvasSource} from '../source/canvas_source';
 
-import type Dispatcher from '../util/dispatcher';
+import type {SourceSpecification} from '@maplibre/maplibre-gl-style-spec';
+import type {Dispatcher} from '../util/dispatcher';
 import type {Event, Evented} from '../util/evented';
-import type Map from '../ui/map';
-import type Tile from './tile';
-import type {OverscaledTileID} from './tile_id';
+import type {Map} from '../ui/map';
+import type {Tile} from './tile';
+import type {OverscaledTileID, CanonicalTileID} from './tile_id';
 import type {Callback} from '../types/callback';
-import {CanonicalTileID} from './tile_id';
+import type {CanvasSourceSpecification} from '../source/canvas_source';
+
+const registeredSources = {} as {[key:string]: SourceClass};
 
 /**
  * The `Source` interface must be implemented by each source type, including "core" types (`vector`, `raster`,
  * `video`, etc.) and all custom, third-party types.
  *
- * @private
- *
- * @param {string} id The id for the source. Must not be used by any existing source.
- * @param {Object} options Source options, specific to the source type (except for `options.type`, which is always
- * required).
- * @param {string} options.type The source type, matching the value of `name` used in {@link Style#addSourceType}.
- * @param {Dispatcher} dispatcher A {@link Dispatcher} instance, which can be used to send messages to the workers.
- *
- * @fires data with `{dataType: 'source', sourceDataType: 'metadata'}` to indicate that any necessary metadata
+ * @event `data` - Fired with `{dataType: 'source', sourceDataType: 'metadata'}` to indicate that any necessary metadata
  * has been loaded so that it's okay to call `loadTile`; and with `{dataType: 'source', sourceDataType: 'content'}`
  * to indicate that the source data has changed, so that any current caches should be flushed.
- * @property {string} id The id for the source.  Must match the id passed to the constructor.
- * @property {number} minzoom
- * @property {number} maxzoom
- * @property {boolean} isTileClipped `false` if tiles can be drawn outside their boundaries, `true` if they cannot.
- * @property {boolean} reparseOverscaled `true` if tiles should be sent back to the worker for each overzoomed zoom
- * level, `false` if not.
- * @property {boolean} roundZoom `true` if zoom levels are rounded to the nearest integer in the source data, `false`
- * if they are floor-ed to the nearest integer.
+ *
+ * @group Sources
  */
 export interface Source {
     readonly type: string;
+    /**
+     * The id for the source. Must not be used by any existing source.
+     */
     id: string;
     minzoom: number;
     maxzoom: number;
     tileSize: number;
     attribution?: string;
+    /**
+     * `true` if zoom levels are rounded to the nearest integer in the source data, `false` if they are floor-ed to the nearest integer.
+     */
     roundZoom?: boolean;
+    /**
+     * `false` if tiles can be drawn outside their boundaries, `true` if they cannot.
+     */
     isTileClipped?: boolean;
     tileID?: CanonicalTileID;
+    /**
+     * `true` if tiles should be sent back to the worker for each overzoomed zoom level, `false` if not.
+     */
     reparseOverscaled?: boolean;
     vectorLayerIds?: Array<string>;
     hasTransition(): boolean;
@@ -57,12 +64,14 @@ export interface Source {
      * @returns A plain (stringifiable) JS object representing the current state of the source.
      * Creating a source using the returned object as the `options` should result in a Source that is
      * equivalent to this one.
-     * @private
      */
     serialize(): any;
     readonly prepare?: () => void;
 }
 
+/**
+ * A supporting type to the source definition
+ */
 type SourceStatics = {
     /*
      * An optional URL to a script which, when run by a Worker, registers a {@link WorkerSource}
@@ -71,59 +80,58 @@ type SourceStatics = {
     workerSourceURL?: URL;
 };
 
+/**
+ * A general definition of a {@link Source} class for factory usage
+ */
 export type SourceClass = {
-    new (...args: any): Source;
+    new (id: string, specification: SourceSpecification | CanvasSourceSpecification, dispatcher: Dispatcher, eventedParent: Evented): Source;
 } & SourceStatics;
 
-import vector from '../source/vector_tile_source';
-import raster from '../source/raster_tile_source';
-import rasterDem from '../source/raster_dem_tile_source';
-import geojson from '../source/geojson_source';
-import video from '../source/video_source';
-import image from '../source/image_source';
-import canvas from '../source/canvas_source';
-
-import type {SourceSpecification} from '@maplibre/maplibre-gl-style-spec';
-
-const sourceTypes = {
-    vector,
-    raster,
-    'raster-dem': rasterDem,
-    geojson,
-    video,
-    image,
-    canvas
-};
-
-/*
+/**
  * Creates a tiled data source instance given an options object.
  *
- * @param id
- * @param {Object} source A source definition object compliant with
+ * @param id - The id for the source. Must not be used by any existing source.
+ * @param specification - Source options, specific to the source type (except for `options.type`, which is always required).
+ * @param source - A source definition object compliant with
  * [`maplibre-gl-style-spec`](https://maplibre.org/maplibre-style-spec/#sources) or, for a third-party source type,
   * with that type's requirements.
- * @param {Dispatcher} dispatcher
- * @returns {Source}
+ * @param dispatcher - A {@link Dispatcher} instance, which can be used to send messages to the workers.
+ * @returns a newly created source
  */
-export const create = function(id: string, specification: SourceSpecification, dispatcher: Dispatcher, eventedParent: Evented) {
-    const source = new sourceTypes[specification.type](id, (specification as any), dispatcher, eventedParent);
+export const create = (id: string, specification: SourceSpecification | CanvasSourceSpecification, dispatcher: Dispatcher, eventedParent: Evented): Source => {
+
+    const Class = getSourceType(specification.type);
+    const source = new Class(id, specification, dispatcher, eventedParent);
 
     if (source.id !== id) {
         throw new Error(`Expected Source id to be ${id} instead of ${source.id}`);
     }
 
-    bindAll(['load', 'abort', 'unload', 'serialize', 'prepare'], source);
     return source;
 };
 
-export const getSourceType = function (name: string) {
-    return sourceTypes[name];
+export const getSourceType = (name: string): SourceClass => {
+    switch (name) {
+        case 'geojson':
+            return GeoJSONSource;
+        case 'image':
+            return ImageSource;
+        case 'raster':
+            return RasterTileSource;
+        case 'raster-dem':
+            return RasterDEMTileSource;
+        case 'vector':
+            return VectorTileSource;
+        case 'video':
+            return VideoSource;
+        case 'canvas':
+            return CanvasSource;
+    }
+    return registeredSources[name];
 };
 
-export const setSourceType = function (name: string, type: {
-    new (...args: any): Source;
-}) {
-    sourceTypes[name] = type;
+export const setSourceType = (name: string, type: SourceClass) => {
+    registeredSources[name] = type;
 };
 
 export interface Actor {

package/src/source/source_cache.test.ts

@@ -1,16 +1,16 @@
-import SourceCache from './source_cache';
+import {SourceCache} from './source_cache';
 import {setSourceType} from './source';
-import Tile from './tile';
+import {Tile} from './tile';
 import {OverscaledTileID} from './tile_id';
-import Transform from '../geo/transform';
-import LngLat from '../geo/lng_lat';
+import {Transform} from '../geo/transform';
+import {LngLat} from '../geo/lng_lat';
 import Point from '@mapbox/point-geometry';
 import {Event, ErrorEvent, Evented} from '../util/evented';
 import {extend} from '../util/util';
-import browser from '../util/browser';
-import Dispatcher from '../util/dispatcher';
+import {browser} from '../util/browser';
+import {Dispatcher} from '../util/dispatcher';
 import {Callback} from '../types/callback';
-import TileBounds from './tile_bounds';
+import {TileBounds} from './tile_bounds';
 
 class SourceMock extends Evented {
     id: string;

package/src/source/source_cache.ts

@@ -1,28 +1,28 @@
 import {create as createSource} from './source';
 
-import Tile from './tile';
+import {Tile} from './tile';
 import {Event, ErrorEvent, Evented} from '../util/evented';
-import TileCache from './tile_cache';
-import MercatorCoordinate from '../geo/mercator_coordinate';
+import {TileCache} from './tile_cache';
+import {MercatorCoordinate} from '../geo/mercator_coordinate';
 import {keysDifference} from '../util/util';
-import EXTENT from '../data/extent';
-import Context from '../gl/context';
+import {EXTENT} from '../data/extent';
+import {Context} from '../gl/context';
 import Point from '@mapbox/point-geometry';
-import browser from '../util/browser';
+import {browser} from '../util/browser';
 import {OverscaledTileID} from './tile_id';
-import SourceFeatureState from './source_state';
+import {SourceFeatureState} from './source_state';
 
 import type {Source} from './source';
-import type Map from '../ui/map';
-import type Style from '../style/style';
-import type Dispatcher from '../util/dispatcher';
-import type Transform from '../geo/transform';
+import type {Map} from '../ui/map';
+import type {Style} from '../style/style';
+import type {Dispatcher} from '../util/dispatcher';
+import type {Transform} from '../geo/transform';
 import type {TileState} from './tile';
 import type {Callback} from '../types/callback';
 import type {SourceSpecification} from '@maplibre/maplibre-gl-style-spec';
 import type {MapSourceDataEvent} from '../ui/events';
-import Terrain from '../render/terrain';
-import config from '../util/config';
+import {Terrain} from '../render/terrain';
+import {config} from '../util/config';
 
 /**
  * `SourceCache` is responsible for
@@ -32,10 +32,8 @@ import config from '../util/config';
  *  - caching tiles loaded from an instance of `Source`
  *  - loading the tiles needed to render a given viewport
  *  - unloading the cached tiles not needed to render a given viewport
- *
- * @private
  */
-class SourceCache extends Evented {
+export class SourceCache extends Evented {
     id: string;
     dispatcher: Dispatcher;
     map: Map;
@@ -138,7 +136,6 @@ class SourceCache extends Evented {
     /**
      * Return true if no tile data is pending, tiles will not change unless
      * an additional API call is received.
-     * @private
      */
     loaded(): boolean {
         if (this._sourceErrored) { return true; }
@@ -208,7 +205,6 @@ class SourceCache extends Evented {
 
     /**
      * Return all tile ids ordered with z-order, and cast to numbers
-     * @private
      */
     getIds(): Array<string> {
         return (Object.values(this._tiles) as any).map((tile: Tile) => tile.tileID).sort(compareTileId).map(id => id.key);
@@ -298,7 +294,6 @@ class SourceCache extends Evented {
 
     /**
     * For raster terrain source, backfill DEM to eliminate visible tile boundaries
-    * @private
     */
     _backfillDEM(tile: Tile) {
         const renderables = this.getRenderableIds();
@@ -339,7 +334,6 @@ class SourceCache extends Evented {
     }
     /**
      * Get a specific tile by TileID
-     * @private
      */
     getTile(tileID: OverscaledTileID): Tile {
         return this.getTileByID(tileID.key);
@@ -347,7 +341,6 @@ class SourceCache extends Evented {
 
     /**
      * Get a specific tile by id
-     * @private
      */
     getTileByID(id: string): Tile {
         return this._tiles[id];
@@ -356,7 +349,6 @@ class SourceCache extends Evented {
     /**
      * For a given set of tiles, retain children that are loaded and have a zoom
      * between `zoom` (exclusive) and `maxCoveringZoom` (inclusive)
-     * @private
      */
     _retainLoadedChildren(
         idealTiles: {
@@ -406,7 +398,6 @@ class SourceCache extends Evented {
 
     /**
      * Find a loaded parent of the given tile (up to minCoveringZoom)
-     * @private
      */
     findLoadedParent(tileID: OverscaledTileID, minCoveringZoom: number): Tile {
         if (tileID.key in this._loadedParentTiles) {
@@ -443,7 +434,6 @@ class SourceCache extends Evented {
      * Larger viewports use more tiles and need larger caches. Larger viewports
      * are more likely to be found on devices with more memory and on pages where
      * the map is more important.
-     * @private
      */
     updateCacheSize(transform: Transform) {
         const widthInTiles = Math.ceil(transform.width / this._source.tileSize) + 1;
@@ -504,7 +494,6 @@ class SourceCache extends Evented {
     /**
      * Removes tiles that are outside the viewport and adds new tiles that
      * are inside the viewport.
-     * @private
      */
     update(transform: Transform, terrain?: Terrain) {
         this.transform = transform;
@@ -801,7 +790,6 @@ class SourceCache extends Evented {
 
     /**
      * Add a tile, given its coordinate, to the pyramid.
-     * @private
      */
     _addTile(tileID: OverscaledTileID): Tile {
         let tile = this._tiles[tileID.key];
@@ -854,7 +842,6 @@ class SourceCache extends Evented {
 
     /**
      * Remove a tile, given its id, from the pyramid
-     * @private
      */
     _removeTile(id: string) {
         const tile = this._tiles[id];
@@ -896,11 +883,10 @@ class SourceCache extends Evented {
     /**
      * Search through our current tiles and attempt to find the tiles that
      * cover the given bounds.
-     * @param pointQueryGeometry coordinates of the corners of bounding rectangle
-     * @returns {Array<Object>} result items have {tile, minX, maxX, minY, maxY}, where min/max bounding values are the given bounds transformed in into the coordinate space of this tile.
-     * @private
+     * @param pointQueryGeometry - coordinates of the corners of bounding rectangle
+     * @returns result items have `{tile, minX, maxX, minY, maxY}`, where min/max bounding values are the given bounds transformed in into the coordinate space of this tile.
      */
-    tilesIn(pointQueryGeometry: Array<Point>, maxPitchScaleFactor: number, has3DLayer: boolean) {
+    tilesIn(pointQueryGeometry: Array<Point>, maxPitchScaleFactor: number, has3DLayer: boolean): any[] {
 
         const tileResults = [];
 
@@ -990,7 +976,6 @@ class SourceCache extends Evented {
 
     /**
      * Set the value of a particular state for a feature
-     * @private
      */
     setFeatureState(sourceLayer: string, featureId: number | string, state: any) {
         sourceLayer = sourceLayer || '_geojsonTileLayer';
@@ -999,7 +984,6 @@ class SourceCache extends Evented {
 
     /**
      * Resets the value of a particular state key for a feature
-     * @private
      */
     removeFeatureState(sourceLayer?: string, featureId?: number | string, key?: string) {
         sourceLayer = sourceLayer || '_geojsonTileLayer';
@@ -1008,7 +992,6 @@ class SourceCache extends Evented {
 
     /**
      * Get the entire state object for a feature
-     * @private
      */
     getFeatureState(sourceLayer: string, featureId: number | string) {
         sourceLayer = sourceLayer || '_geojsonTileLayer';
@@ -1018,7 +1001,6 @@ class SourceCache extends Evented {
     /**
      * Sets the set of keys that the tile depends on. This allows tiles to
      * be reloaded when their dependencies change.
-     * @private
      */
     setDependencies(tileKey: string, namespace: string, dependencies: Array<string>) {
         const tile = this._tiles[tileKey];
@@ -1029,7 +1011,6 @@ class SourceCache extends Evented {
 
     /**
      * Reloads all tiles that depend on the given keys.
-     * @private
      */
     reloadTilesForDependencies(namespaces: Array<string>, keys: Array<string>) {
         for (const id in this._tiles) {
@@ -1057,5 +1038,3 @@ function compareTileId(a: OverscaledTileID, b: OverscaledTileID): number {
 function isRasterType(type) {
     return type === 'raster' || type === 'image' || type === 'video';
 }
-
-export default SourceCache;

package/src/source/source_state.ts

@@ -1,5 +1,5 @@
 import {extend} from '../util/util';
-import Tile from './tile';
+import {Tile} from './tile';
 import type {FeatureState} from '@maplibre/maplibre-gl-style-spec';
 
 export type FeatureStates = {[featureId: string]: FeatureState};
@@ -12,9 +12,8 @@ export type LayerFeatureStates = {[layer: string]: FeatureStates};
  * between coalesce() events. addFeatureState() and removeFeatureState() also update their counterpart's
  * list of changes, such that coalesce() can apply the proper state changes while agnostic to the order of operations.
  * In deletedStates, all null's denote complete removal of state at that scope
- * @private
 */
-class SourceFeatureState {
+export class SourceFeatureState {
     state: LayerFeatureStates;
     stateChanges: LayerFeatureStates;
     deletedStates: {};
@@ -155,5 +154,3 @@ class SourceFeatureState {
         }
     }
 }
-
-export default SourceFeatureState;

package/src/source/terrain_source_cache.test.ts

@@ -1,15 +1,15 @@
-import TerrainSourceCache from './terrain_source_cache';
-import Style from '../style/style';
+import {TerrainSourceCache} from './terrain_source_cache';
+import {Style} from '../style/style';
 import {RequestManager} from '../util/request_manager';
-import Dispatcher from '../util/dispatcher';
+import {Dispatcher} from '../util/dispatcher';
 import {fakeServer, FakeServer} from 'nise';
-import Transform from '../geo/transform';
+import {Transform} from '../geo/transform';
 import {Evented} from '../util/evented';
-import Painter from '../render/painter';
-import RasterDEMTileSource from './raster_dem_tile_source';
+import {Painter} from '../render/painter';
+import {RasterDEMTileSource} from './raster_dem_tile_source';
 import {OverscaledTileID} from './tile_id';
-import Tile from './tile';
-import DEMData from '../data/dem_data';
+import {Tile} from './tile';
+import {DEMData} from '../data/dem_data';
 
 const transform = new Transform();
 

package/src/source/terrain_source_cache.ts

@@ -1,11 +1,11 @@
 import {OverscaledTileID} from './tile_id';
-import Tile from './tile';
-import EXTENT from '../data/extent';
+import {Tile} from './tile';
+import {EXTENT} from '../data/extent';
 import {mat4} from 'gl-matrix';
 import {Evented} from '../util/evented';
-import type Transform from '../geo/transform';
-import type SourceCache from '../source/source_cache';
-import Terrain from '../render/terrain';
+import type {Transform} from '../geo/transform';
+import type {SourceCache} from '../source/source_cache';
+import {Terrain} from '../render/terrain';
 
 /**
  * This class is a helper for the Terrain-class, it:
@@ -15,23 +15,38 @@ import Terrain from '../render/terrain';
  *   - finds all necessary renderToTexture tiles for a OverscaledTileID area
  *   - finds the corresponding raster-dem tile for OverscaledTileID
  */
-
-export default class TerrainSourceCache extends Evented {
-    // source-cache for the raster-dem source.
+export class TerrainSourceCache extends Evented {
+    /**
+     * source-cache for the raster-dem source.
+     */
     sourceCache: SourceCache;
-    // stores all render-to-texture tiles.
+    /**
+     * stores all render-to-texture tiles.
+     */
     _tiles: {[_: string]: Tile};
-    // contains a list of tileID-keys for the current scene. (only for performance)
+    /**
+     * contains a list of tileID-keys for the current scene. (only for performance)
+     */
     _renderableTilesKeys: Array<string>;
-    // raster-dem-tile for a TileID cache.
+    /**
+     * raster-dem-tile for a TileID cache.
+     */
     _sourceTileCache: {[_: string]: string};
-    // minimum zoomlevel to render the terrain.
+    /**
+     * minimum zoomlevel to render the terrain.
+     */
     minzoom: number;
-    // maximum zoomlevel to render the terrain.
+    /**
+     * maximum zoomlevel to render the terrain.
+     */
     maxzoom: number;
-    // render-to-texture tileSize in scene.
+    /**
+     * render-to-texture tileSize in scene.
+     */
     tileSize: number;
-    // raster-dem tiles will load for performance the actualZoom - deltaZoom zoom-level.
+    /**
+     * raster-dem tiles will load for performance the actualZoom - deltaZoom zoom-level.
+     */
     deltaZoom: number;
 
     constructor(sourceCache: SourceCache) {
@@ -55,8 +70,8 @@ export default class TerrainSourceCache extends Evented {
 
     /**
      * Load Terrain Tiles, create internal render-to-texture tiles, free GPU memory.
-     * @param {Transform} transform - the operation to do
-     * @param {Terrain} terrain - the terrain
+     * @param transform - the operation to do
+     * @param terrain - the terrain
      */
     update(transform: Transform, terrain: Terrain): void {
         // load raster-dem tiles for the current scene.
@@ -87,7 +102,7 @@ export default class TerrainSourceCache extends Evented {
 
     /**
      * Free render to texture cache
-     * @param {TileID} tileID optional, free only corresponding to tileID.
+     * @param tileID - optional, free only corresponding to tileID.
      */
     freeRtt(tileID?: OverscaledTileID) {
         for (const key in this._tiles) {
@@ -99,7 +114,7 @@ export default class TerrainSourceCache extends Evented {
 
     /**
      * get a list of tiles, which are loaded and should be rendered in the current scene
-     * @returns {Array<Tile>} the renderable tiles
+     * @returns the renderable tiles
      */
     getRenderableTiles(): Array<Tile> {
         return this._renderableTilesKeys.map(key => this.getTileByID(key));
@@ -108,7 +123,7 @@ export default class TerrainSourceCache extends Evented {
     /**
      * get terrain tile by the TileID key
      * @param id - the tile id
-     * @returns {Tile} - the tile
+     * @returns the tile
      */
     getTileByID(id: string): Tile {
         return this._tiles[id];
@@ -116,8 +131,8 @@ export default class TerrainSourceCache extends Evented {
 
     /**
      * Searches for the corresponding current renderable terrain-tiles
-     * @param {OverscaledTileID} tileID - the tile to look for
-     * @returns {Record<string, OverscaledTileID>} - the tiles that were found
+     * @param tileID - the tile to look for
+     * @returns the tiles that were found
      */
     getTerrainCoords(tileID: OverscaledTileID): Record<string, OverscaledTileID> {
         const coords = {};
@@ -156,9 +171,9 @@ export default class TerrainSourceCache extends Evented {
 
     /**
      * find the covering raster-dem tile
-     * @param {OverscaledTileID} tileID - the tile to look for
-     * @param {boolean} searchForDEM Optinal parameter to search for (parent) souretiles with loaded dem.
-     * @returns {Tile} - the tile
+     * @param tileID - the tile to look for
+     * @param searchForDEM - Optinal parameter to search for (parent) souretiles with loaded dem.
+     * @returns the tile
      */
     getSourceTile(tileID: OverscaledTileID, searchForDEM?: boolean): Tile {
         const source = this.sourceCache._source;
@@ -178,8 +193,8 @@ export default class TerrainSourceCache extends Evented {
 
     /**
      * get a list of tiles, loaded after a spezific time. This is used to update depth & coords framebuffers.
-     * @param {Date} time - the time
-     * @returns {Array<Tile>} - the relevant tiles
+     * @param time - the time
+     * @returns the relevant tiles
      */
     tilesAfterTime(time = Date.now()): Array<Tile> {
         return Object.values(this._tiles).filter(t => t.timeAdded >= time);

package/src/source/tile.test.ts

@@ -1,11 +1,11 @@
 import {createSymbolBucket} from '../../test/unit/lib/create_symbol_layer';
-import Tile from '../source/tile';
-import GeoJSONWrapper, {Feature} from '../source/geojson_wrapper';
+import {Tile} from '../source/tile';
+import {GeoJSONWrapper, Feature} from '../source/geojson_wrapper';
 import {OverscaledTileID} from '../source/tile_id';
 import fs from 'fs';
 import path from 'path';
 import vtpbf from 'vt-pbf';
-import FeatureIndex from '../data/feature_index';
+import {FeatureIndex} from '../data/feature_index';
 import {CollisionBoxArray} from '../data/array_types.g';
 import {extend} from '../util/util';
 import {serialize, deserialize} from '../util/web_worker_transfer';