Add Map#loadImage method and Map#addImage examples

docs/_posts/examples/.eslintrc

@@ -5,7 +5,8 @@
     "MapboxGeocoder": true,
     "MapboxDirections": true,
     "turf": true,
-    "d3": true
+    "d3": true,
+    "Uint8Array": true
   },
   "rules": {
     "strict": "off",

docs/_posts/examples/3400-01-31-add-image-generated.html

@@ -0,0 +1,59 @@
+---
+layout: example
+category: example
+title: Add a generated icon to the map
+description: Add an icon to the map that was generated at runtime.
+tags:
+  - styles
+  - layers
+---
+<div id='map'></div>
+
+<script>
+
+var map = new mapboxgl.Map({
+    container: 'map',
+    style: 'mapbox://styles/mapbox/streets-v9'
+});
+
+map.on('load', () => {
+
+    const width = 64; // The image will be 64 pixels square
+    const bytesPerPixel = 4; // Each pixel is represented by 4 bytes: red, green, blue, and alpha.
+    const image = new Uint8Array(width * width * bytesPerPixel);
+
+    for (var x = 0; x < width; x++) {
+        for (var y = 0; y < width; y++) {
+            const offset = (y * width + x) * bytesPerPixel;
+            image[offset + 0] = y / width * 255; // red
+            image[offset + 1] = x / width * 255; // green
+            image[offset + 2] = 128;             // blue
+            image[offset + 3] = 255;             // alpha
+        }
+    }
+
+    map.addImage('gradient', image, {width: width, height: width});
+
+    map.addLayer({
+        "id": "points",
+        "type": "symbol",
+        "source": {
+            "type": "geojson",
+            "data": {
+                "type": "FeatureCollection",
+                "features": [{
+                    "type": "Feature",
+                    "geometry": {
+                        "type": "Point",
+                        "coordinates": [0, 0]
+                    }
+                }]
+            }
+        },
+        "layout": {
+            "icon-image": "gradient"
+        }
+    });
+});
+
+</script>

docs/_posts/examples/3400-01-31-add-image.html

@@ -0,0 +1,47 @@
+---
+layout: example
+category: example
+title: Add an icon to the map
+description: Add an icon to the map from an external URL and use it in a symbol layer.
+tags:
+  - styles
+  - layers
+---
+<div id='map'></div>
+
+<script>
+
+var map = new mapboxgl.Map({
+    container: 'map',
+    style: 'mapbox://styles/mapbox/streets-v9'
+});
+
+map.on('load', () => {
+    map.loadImage('https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Cat_silhouette.svg/400px-Cat_silhouette.svg.png', (error, image) => {
+        if (error) throw error;
+        map.addImage('cat', image);
+        map.addLayer({
+            "id": "points",
+            "type": "symbol",
+            "source": {
+                "type": "geojson",
+                "data": {
+                    "type": "FeatureCollection",
+                    "features": [{
+                        "type": "Feature",
+                        "geometry": {
+                            "type": "Point",
+                            "coordinates": [0, 0]
+                        }
+                    }]
+                }
+            },
+            "layout": {
+                "icon-image": "cat",
+                "icon-size": 0.25
+            }
+        });
+    });
+});
+
+</script>

src/ui/map.js

@@ -4,6 +4,7 @@ const util = require('../util/util');
 const browser = require('../util/browser');
 const window = require('../util/window');
 const DOM = require('../util/dom');
+const ajax = require('../util/ajax');
 
 const Style = require('../style/style');
 const AnimationLoop = require('../style/animation_loop');
@@ -823,6 +824,8 @@ class Map extends Camera {
      * {@link Map#error} event will be fired if there is not enough space in the
      * sprite to add this image.
      *
+     * @see [Add an icon to the map](https://www.mapbox.com/mapbox-gl-js/example/add-image/)
+     * @see [Add a generated icon to the map](https://www.mapbox.com/mapbox-gl-js/example/add-image-generated/)
      * @param {string} name The name of the image.
      * @param {HTMLImageElement|ArrayBufferView} image The image as an `HTMLImageElement` or `ArrayBufferView` (using the format of [`ImageData#data`](https://developer.mozilla.org/en-US/docs/Web/API/ImageData/data))
      * @param {Object} [options] Required if and only if passing an `ArrayBufferView`
@@ -843,6 +846,18 @@ class Map extends Camera {
         this.style.spriteAtlas.removeImage(name);
     }
 
+    /**
+     * Load an image from an external URL for use with `Map#addImage`. External
+     * domains must support [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Access_control_CORS).
+     *
+     * @param {string} url The URL of the image.
+     * @param {Function} callback Called when the image has loaded or with an error argument if there is an error.
+     * @see [Add an icon to the map](https://www.mapbox.com/mapbox-gl-js/example/add-image/)
+     */
+    loadImage(url, callback) {
+        ajax.getImage(url, callback);
+    }
+
     /**
      * Adds a [Mapbox style layer](https://www.mapbox.com/mapbox-gl-style-spec/#layers)
      * to the map's style.