azure-maps-control 2.1.17 → 2.2.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "azure-maps-control",
   "author": "Microsoft Corporation",
-  "version": "2.1.17",
+  "version": "2.2.0",
   "description": "Map SDK for Azure Maps",
   "keywords": [
     "azure",

package/typings/index.d.ts

@@ -516,6 +516,78 @@ declare namespace atlas {
             constructor(geometries: Geometry[]);
         }
 
+        /**
+         * A `MercatorPoint` object represents a projected three dimensional position.
+         *
+         * `MercatorPoint` uses the web mercator projection ([EPSG:3857](https://epsg.io/3857)) with slightly different units:
+         * - the size of 1 unit is the width of the projected world instead of the "mercator meter"
+         * - the origin of the coordinate space is at the north-west corner instead of the middle.
+         *
+         * For example, `MercatorPoint(0, 0, 0)` is the north-west corner of the mercator world and
+         * `MercatorPoint(1, 1, 0)` is the south-east corner. If you are familiar with
+         * [vector tiles](https://github.com/mapbox/vector-tile-spec) it may be helpful to think
+         * of the coordinate space as the `0/0/0` tile with an extent of `1`.
+         *
+         * The `z` dimension of `MercatorPoint` is conformal. A cube in the mercator coordinate space would be rendered as a cube.
+         */
+        export class MercatorPoint extends Array<number> {
+            /**
+             * Constructs a MercatorPoint.
+             * @param x A points x position in mercator units.
+             * @param y A points y position in mercator units.
+             * @param z A points z position in mercator units.
+             */
+            constructor(x: number, y: number, z?: number);
+            /**
+             * Converts a position into a mercator point.
+             * @param position Position to convert.
+             * @returns A mercator point.
+             */
+            static fromPosition(position: Position): MercatorPoint;
+            /**
+             * Converts an array of positions into an array of mercator points.
+             * @param positions Array of positions to convert.
+             * @returns An array of  mercator points.
+             */
+            static fromPositions(positions: Position[]): MercatorPoint[];
+            /**
+             * Converts an array of positions into a Float32Array of mercator xyz values.
+             * @param positions Array of positions to convert.
+             * @returns A Float32Array of mercator xyz values.
+             */
+            static toFloat32Array(positions: Position[]): Float32Array;
+            /**
+             * Converts a mercator point into a map position.
+             * @param mercator Mercator point to convert.
+             * @returns A map position.
+             */
+            static toPosition(mercator: MercatorPoint): Position;
+            /**
+             * Converts an array of mercator points into an array of map positions.
+             * @param mercators Mercator points to convert.
+             * @returns An array of map positions.
+             */
+            static toPositions(mercators: MercatorPoint[]): Position[];
+            /**
+             * Determine the Mercator scale factor for a given latitude, see
+             * https://en.wikipedia.org/wiki/Mercator_projection#Scale_factor
+             *
+             * At the equator the scale factor will be 1, which increases at higher latitudes.
+             *
+             * @param latitude Latitude
+             * @returns The mercator scale factor.
+             */
+            static mercatorScale(latitude: number): number;
+            /**
+             * Returns the distance of 1 meter in `MercatorPoint` units at this latitude.
+             *
+             * For coordinates in real world units using meters, this naturally provides the scale
+             * to transform into `MercatorPoint`s.
+             *
+             * @returns {number} Distance of 1 meter in `MercatorPoint` units.
+             */
+            static meterInMercatorUnits(latitude: number): number;
+        }
     }
 
     //control classes
@@ -817,7 +889,6 @@ declare namespace atlas {
              * @param newOptions The new options of the bubble layer.
              */
             setOptions(options: BubbleLayerOptions): void;
-
         }
 
         export interface LayerEvents {
@@ -1072,6 +1143,27 @@ declare namespace atlas {
              */
             setOptions(options: TileLayerOptions): void;
         }
+
+        /**
+         * Enables custom rendering logic with access to the WebGL context of the map.
+         */
+         export class WebGLLayer extends Layer {
+            /**
+             * Constructs a new WebGLLayer.
+             * @param id The id of the layer. If not specified a random one will be generated.
+             * @param options The options of the WebGL layer.
+            */
+            constructor(id?: string, options?: WebGLLayerOptions);
+            /**
+             * Gets the options of the WebGL layer.
+             */
+            getOptions(): WebGLLayerOptions;
+            /**
+             * Sets the options of the WebGL layer.
+             * @param options The new options of the WebGL layer.
+             */
+            setOptions(options: WebGLLayerOptions): void;
+        }
     }
 
     //source classes
@@ -1971,6 +2063,14 @@ declare namespace atlas {
          * Stops any animated transition that is currently underway.
          */
         stop(): void;
+        /**
+         * Trigger the rendering of a single frame.
+         * Use this method with WebGL layers to repaint the map when the layer's
+         * properties or properties associated with the layer's source change.
+         * Calling this multiple times before the next frame is rendered will still
+         * result in only a single frame being rendered.
+         */
+        triggerRepaint(): void;
         /**
          * The callback used when styleOptions.autoResize is true.
          */
@@ -3524,6 +3624,16 @@ declare namespace atlas {
         tileUrl?: string;
     }
 
+    /**
+     * Options used to render graphics in a WebGLLayer.
+     */
+     export interface WebGLLayerOptions extends LayerOptions {
+        /**
+         * An object that contains the rendering logic.
+         */
+        renderer?: WebGLRenderer;
+    }
+
     /**
      * Available styles for a Control.
      */
@@ -4131,6 +4241,10 @@ declare namespace atlas {
      * The options for the map's style.
      */
     export interface StyleOptions extends Options {
+        /**
+         * If true, the gl context will be created with MSAA antialiasing, which can be useful for antialiasing WebGL layers.
+         */
+        antialias?: boolean;
         /**
          * If true the map will automatically resize whenever the window's size changes.
          * Otherwise map.resize() must be called.
@@ -4467,21 +4581,21 @@ declare namespace atlas {
         | 'Thumbnail';
 
     /**
-     * Represents the contents of the style set.
+     * Represents the contents of map configuration holding a list of styles available to them.
      */
-    export interface StyleSet {
+    export interface MapConfiguration {
         created?: string;
-        defaultStyle: string;
+        defaultConfiguration: string;
         description?: string;
         id?: string;
-        styles: StyleSetStyle[];
+        configurations: MapConfigurationStyle[];
         version?: number;
     }
 
     /**
      * Represents the info for a single style.
      */
-    export interface StyleSetStyle {
+    export interface MapConfigurationStyle {
         copyright?: string;
         displayName?: string;
         name: string;
@@ -4517,10 +4631,9 @@ declare namespace atlas {
          */
         domain?: string;
         /**
-         * The style set of the map. Determines which styles are available to be picked
-         * and what do they consist of (style names, thumbnails, URLs, etc).
+         * The map configuration defines the set of styles available to the map. 
          */
-        styleSet?: StyleSet;
+        mapConfiguration?: string | MapConfiguration;
         /**
          * Enable accessibility
          * default: true
@@ -4608,6 +4721,75 @@ declare namespace atlas {
     export interface AggregateExpression extends Array<any> {
     }
 
+    /**
+     * Interface for rendering WebGL graphics in a WebGLLayer.
+     */
+    export interface WebGLRenderer {
+        /**
+         * Either "2d" or "3d". Defaults to "2d".
+         */
+        renderingMode?: "2d" | "3d";
+
+        /**
+         * Optional method called when the layer has been added to the Map.
+         * This gives the layer a chance to initialize gl resources and register event listeners.
+         * @param map The Map this WebGL layer was just added to.
+         * @param gl The gl context for the map.
+         */
+        onAdd?(map: Map, gl: WebGLRenderingContext): void;
+
+        /**
+         * Optional method called when the layer has been removed from the Map.
+         * This gives the layer a chance to clean up gl resources and event listeners.
+         * @param map The Map this WebGL layer was just added to.
+         * @param gl The gl context for the map.
+         */
+        onRemove?(map: Map, gl: WebGLRenderingContext): void;
+
+        /**
+         * Optional method called during a render frame to allow a layer to prepare resources
+         * or render into a texture.
+         *
+         * The layer cannot make any assumptions about the current GL state and must bind a framebuffer
+         * before rendering.
+         * @param gl The map's gl context.
+         * @param matrix The map's camera matrix. It projects spherical mercator coordinates to gl
+         *               coordinates. The mercator coordinate  [0, 0] represents the top left corner of
+         *               the mercator world and  [1, 1] represents the bottom right corner. When the
+         *               renderingMode is  "3d" , the z coordinate is conformal. A box with identical
+         *               x, y, and z lengths in mercator units would be rendered as a cube.
+         *               MercatorCoordinate .fromLatLng can be used to project a  LngLat to a mercator
+         *               coordinate.
+         */
+        prerender?(gl: WebGLRenderingContext, matrix: number[]): void;
+
+        /**
+         * Called during a render frame allowing the layer to draw into the GL context.
+         *
+         * The layer can assume blending and depth state is set to allow the layer to properly blend
+         * and clip other layers. The layer cannot make any other assumptions about the current GL state.
+         *
+         * If the layer needs to render to a texture, it should implement the prerender method to do this
+         * and only use the render method for drawing directly into the main framebuffer.
+         *
+         * The blend function is set to gl.blendFunc(gl.ONE, gl.ONE_MINUS_SRC_ALPHA). This expects
+         * colors to be provided in premultiplied alpha form where the r, g and b values are already
+         * multiplied by the a value. If you are unable to provide colors in premultiplied form you may
+         * want to change the blend function to
+         * gl.blendFuncSeparate(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA, gl.ONE, gl.ONE_MINUS_SRC_ALPHA).
+         *
+         * @param gl The map's gl context.
+         * @param matrix The map's camera matrix. It projects spherical mercator coordinates to gl
+         *               coordinates. The mercator coordinate  [0, 0] represents the top left corner of
+         *               the mercator world and  [1, 1] represents the bottom right corner. When the
+         *               renderingMode is  "3d" , the z coordinate is conformal. A box with identical
+         *               x, y, and z lengths in mercator units would be rendered as a cube.
+         *               MercatorCoordinate .fromLatLng can be used to project a  LngLat to a mercator
+         *               coordinate.
+         */
+        render(gl: WebGLRenderingContext, matrix: number[]): void;
+    }
+
     /**
      * A manager for the map control's authentication.
      * Exposed through the authentication property of the atlas.Map class.
@@ -4707,11 +4889,11 @@ declare namespace atlas {
          */
         add(eventType: "stylechanged", callback: (e: StyleChangedEvent) => void): void;
         /**
-         * Adds a styleset change event to the map.
-         * @param eventType A styleset changed event name
+         * Adds a mapConfiguration change event to the map.
+         * @param eventType A mapConfiguration changed event name
          * @param callback The event handler callback
          */
-        add(eventType: "stylesetchanged", callback: (e: StyleSet) => void): void;
+        add(eventType: "mapconfigurationchanged", callback: (e: MapConfiguration) => void): void;
         /**
          * Adds a wheel event to the map.
          * @param eventType The wheel event name.
@@ -4988,7 +5170,7 @@ declare namespace atlas {
          * @param eventType The event name.
          * @param callback The event handler callback.
          */
-        remove(eventType: string, callback: (e: void | atlas.layer.Layer | MapEvent | MapDataEvent | MapMouseEvent | MapTouchEvent | MapMouseWheelEvent | atlas.source.Source | string | StyleSet) => void): void;
+        remove(eventType: string, callback: (e: void | atlas.layer.Layer | MapEvent | MapDataEvent | MapMouseEvent | MapTouchEvent | MapMouseWheelEvent | atlas.source.Source | string | MapConfiguration) => void): void;
         /**
          * Removes an event listener from the DataSource(s).
          * @param eventType The event name.