Add documentation of the public facing fog APIs + revise defaults

debug/fog.html

@@ -33,11 +33,11 @@
     this.enableSky = true;
     this.terrainExaggeration = 1.5;
     this.style = 'satellite-streets-v11';
-    this.fogRangeStart = 1.5;
-    this.fogRangeEnd = 2.0;
+    this.fogRangeStart = 2;
+    this.fogRangeEnd = 12.0;
     this.fogColor = [255, 255, 255];
     this.fogHazeColor = [109, 123, 180];
-    this.fogHazeEnergy = 1.0;
+    this.fogHazeEnergy = 0.8;
     this.fogStrength = 1.0;
     this.fogSkyBlend = 0.1;
     this.showTileBoundaries = false;

src/style-spec/reference/v8.json

@@ -63,7 +63,7 @@
     },
     "fog": {
       "type": "fog",
-      "doc": ""
+      "doc": "A global effect that fades layers and markers based on their distance to the camera. The fog can be used to approximate the effect of atmosphere on distant objects and enhance the depth perception of the map when used with terrain or 3D features."
     },
     "sources": {
       "required": true,
@@ -3681,8 +3681,8 @@
     "range": {
       "type": "array",
       "default": [
-        5,
-        10
+        2,
+        12
       ],
       "minimum": 0,
       "maximum": 20,
@@ -3696,17 +3696,14 @@
           "zoom"
         ]
       },
-      "doc": "",
+      "doc": "The near and far limits of the fog layer. Units are relative to the map height, so that 2.0 corresponds to twice the map height, in pixels.",
       "example": [
-        5,
-        10
+        2,
+        12
       ],
       "sdk-support": {
         "basic functionality": {
-          "js": "",
-          "android": "",
-          "ios": "",
-          "macos": ""
+          "js": "2.3.0"
         }
       }
     },
@@ -3721,13 +3718,10 @@
         ]
       },
       "transition": true,
-      "doc": "",
+      "doc": "The color of the fog. If provided as an `rgba` color, the alpha component is unused.",
       "sdk-support": {
         "basic functionality": {
-          "js": "",
-          "android": "",
-          "ios": "",
-          "macos": ""
+          "js": "2.3.0"
         }
       }
     },
@@ -3742,13 +3736,10 @@
         ]
       },
       "transition": true,
-      "doc": "",
+      "doc": "The color of the haze component of the fog, used only when haze energy is nonzero. If provided as an `rgba` color, the alpha component is unused.",
       "sdk-support": {
         "basic functionality": {
-          "js": "",
-          "android": "",
-          "ios": "",
-          "macos": ""
+          "js": "2.3.0"
         }
       }
     },
@@ -3764,20 +3755,17 @@
         ]
       },
       "transition": true,
-      "doc": "",
+      "doc": "Controls the strength of the fog effect. Reducing the fog strength pushes the fog farther toward the horizon, leaving more visible space for haze, if enabled. When haze energy is zero, this will usually be 1.0.",
       "sdk-support": {
         "basic functionality": {
-          "js": "",
-          "android": "",
-          "ios": "",
-          "macos": ""
+          "js": "2.3.0"
         }
       }
     },
     "haze-energy": {
       "type": "number",
       "property-type": "data-constant",
-      "default": 1.0,
+      "default": 0.0,
       "minimum": 0.0,
       "expression": {
         "interpolated": true,
@@ -3786,20 +3774,17 @@
         ]
       },
       "transition": true,
-      "doc": "",
+      "doc": "Controls the strength of haze in the fog layer. Haze is an additive effect which approximates the look of an atmosphere. Increasing this strengthens the haze. Reducing the fog strength pushes fog toward the horizon, making haze visible.",
       "sdk-support": {
         "basic functionality": {
-          "js": "",
-          "android": "",
-          "ios": "",
-          "macos": ""
+          "js": "2.3.0"
         }
       }
     },
     "sky-blend": {
       "type": "number",
       "property-type": "data-constant",
-      "default": 1,
+      "default": 0.1,
       "minimum": 0,
       "maximum": 1,
       "expression": {
@@ -3809,13 +3794,10 @@
         ]
       },
       "transition": true,
-      "doc": "",
+      "doc": "The sky blend allows to blend the effect of the fog above the horizon line. A value of 1 will entirely blend the fog onto the sky, while a value of 0 will leave the sky unaffected by fog.",
       "sdk-support": {
         "basic functionality": {
-          "js": "",
-          "android": "",
-          "ios": "",
-          "macos": ""
+          "js": "2.3.0"
         }
       }
     }

src/style/fog.js

@@ -23,12 +23,12 @@ type Props = {|
     "sky-blend": DataConstantProperty<number>,
 |};
 
-const properties: Properties<Props> = new Properties({
+const fogProperties: Properties<Props> = new Properties({
     "range": new DataConstantProperty(styleSpec.fog.range),
     "color": new DataConstantProperty(styleSpec.fog.color),
     "haze-color": new DataConstantProperty(styleSpec.fog["haze-color"]),
-    "haze-energy": new DataConstantProperty(styleSpec.fog["strength"]),
-    "strength": new DataConstantProperty(styleSpec.fog["haze-energy"]),
+    "haze-energy": new DataConstantProperty(styleSpec.fog["haze-energy"]),
+    "strength": new DataConstantProperty(styleSpec.fog["strength"]),
     "sky-blend": new DataConstantProperty(styleSpec.fog["sky-blend"]),
 });
 
@@ -41,7 +41,7 @@ class Fog extends Evented {
 
     constructor(fogOptions?: FogSpecification) {
         super();
-        this._transitionable = new Transitionable(properties);
+        this._transitionable = new Transitionable(fogProperties);
         this.set(fogOptions);
         this._transitioning = this._transitionable.untransitioned();
     }

src/ui/map.js

@@ -2174,17 +2174,47 @@ class Map extends Camera {
         return this.style ? this.style.getTerrain() : null;
     }
 
+    /**
+     * Sets the fog property of the style.
+     * @param fog The fog properties to set. Must conform the [Mapbox Style Specification](https://docs.mapbox.com/mapbox-gl-js/style-spec/root/#fog).
+     * If `null` or `undefined` is provided, this function call removes the fog from the map.
+     * @returns {Map} `this`
+     * @example
+     * map.setFog({
+     *  "range": [1.0, 12.0],
+     *  "color": 'white',
+     *  "haze-color": 'rgba(109, 123, 180, 1.0)',
+     *  "strength": 1.0,
+     *  "haze-energy": 1.0,
+     *  "sky-blend": 0.1
+     * });
+     */
     setFog(fog: FogSpecification) {
         this._lazyInitEmptyStyle();
         this.style.setFog(fog);
         return this._update(true);
     }
 
-    // NOTE: Make fog non-optional
+    /**
+     * Returns the fog specification or `null` if fog is not set on the map.
+     *
+     * @returns {Object} fog Fog specification properties of the style.
+     */
     getFog(): Fog | null {
         return this.style ? this.style.getFog() : null;
     }
 
+    /**
+     * Returns the fog opacity for a given geolocation.
+     *
+     * An opacity of 0 means that there is no fog contribution for the given geolocation
+     * while a fog opacity of 1.0 means the geolocation is fully obscured by the fog effect.
+     *
+     * If there is no fog set on the map, this function will simply return 0.
+     *
+     * @param {LngLatLike} lnglat The geographical location to evaluate the fog on.
+     * @returns {number} A value between 0 and 1 representing the fog opacity, where 1 means fully within, and 0 means not affected by the fog effect.
+     */
     getFogOpacity(lnglat: LngLatLike): number {
         if (!this.style || !this.style.fog) return 0.0;
         return this.style.fog.getOpacityAtLatLng(LngLat.convert(lnglat), this.transform);