add styleimagemissing event for on-demand images

docs/pages/example/add-image-missing-generated.html

@@ -0,0 +1,81 @@
+<div id='map'></div>
+
+<script>
+
+var map = new mapboxgl.Map({
+ container: 'map',
+ style: 'mapbox://styles/mapbox/streets-v9'
+});
+
+map.on('styleimagemissing', function(e) {
+ var id = e.id; // id of the missing image
+
+ // check if this missing icon is one this function can generate
+ var prefix = 'square-rgb-';
+ if (id.indexOf(prefix) !== 0) return;
+
+ // extract the color from the id
+ var rgb = id.replace(prefix, '').split(',').map(Number);
+
+ var width = 64; // The image will be 64 pixels square
+ var bytesPerPixel = 4; // Each pixel is represented by 4 bytes: red, green, blue, and alpha.
+ var data = new Uint8Array(width * width * bytesPerPixel);
+
+ for (var x = 0; x < width; x++) {
+ for (var y = 0; y < width; y++) {
+ var offset = (y * width + x) * bytesPerPixel;
+ data[offset + 0] = rgb[0]; // red
+ data[offset + 1] = rgb[1]; // green
+ data[offset + 2] = rgb[2]; // blue
+ data[offset + 3] = 255; // alpha
+ }
+ }
+
+ map.addImage(id, {width: width, height: width, data: data});
+});
+
+map.on('load', function () {
+ map.addLayer({
+ "id": "points",
+ "type": "symbol",
+ "source": {
+ "type": "geojson",
+ "data": {
+ "type": "FeatureCollection",
+ "features": [{
+ "type": "Feature",
+ "geometry": {
+ "type": "Point",
+ "coordinates": [0, 0]
+ },
+ "properties": {
+ "color": "255,0,0"
+ }
+ }, {
+ "type": "Feature",
+ "geometry": {
+ "type": "Point",
+ "coordinates": [50, 0]
+ },
+ "properties": {
+ "color": "255,209,28"
+ }
+ }, {
+ "type": "Feature",
+ "geometry": {
+ "type": "Point",
+ "coordinates": [-50, 0]
+ },
+ "properties": {
+ "color": "242,127,32"
+ }
+ }]
+ }
+ },
+ "layout": {
+ "icon-image": ["concat", "square-rgb-", ["get", "color"]]
+ }
+ });
+});
+
+</script>

docs/pages/example/add-image-missing-generated.js

@@ -0,0 +1,11 @@
+/*---
+title: Generate and add a missing icon to the map
+description: Dynamically generate a missing icon at runtime and add it to the map.
+tags:
+ - styles
+ - layers
+pathname: /mapbox-gl-js/example/add-image-missing-generated/
+---*/
+import Example from '../../components/example';
+import html from './add-image-missing-generated.html';
+export default Example(html);

src/render/image_manager.js

@@ -2,6 +2,7 @@
 
 import potpack from 'potpack';
 
+import { Event, Evented } from '../util/evented';
 import { RGBAImage } from '../util/image';
 import { ImagePosition } from './image_atlas';
 import Texture from './texture';
@@ -33,7 +34,7 @@ const padding = 1;
  data-driven support for `*-pattern`, we'll likely use per-bucket pattern atlases, and that would be a good time
  to refactor this.
 */
-class ImageManager {
+class ImageManager extends Evented {
  images: {[string]: StyleImage};
  loaded: boolean;
  requestors: Array<{ids: Array<string>, callback: Callback<{[string]: StyleImage}>}>;
@@ -44,6 +45,7 @@ class ImageManager {
  dirty: boolean;
 
  constructor() {
+ super();
  this.images = {};
  this.loaded = false;
  this.requestors = [];
@@ -115,6 +117,9 @@ class ImageManager {
  const response = {};
 
  for (const id of ids) {
+ if (!this.images[id]) {
+ this.fire(new Event('styleimagemissing', { id }));
+ }
  const image = this.images[id];
  if (image) {
  // Clone the image so that our own copy of its ArrayBuffer doesn't get transferred.

src/style/style.js

@@ -136,6 +136,7 @@ class Style extends Evented {
  this.map = map;
  this.dispatcher = new Dispatcher(getWorkerPool(), this);
  this.imageManager = new ImageManager();
+ this.imageManager.setEventedParent(this);
  this.glyphManager = new GlyphManager(map._transformRequest, options.localIdeographFontFamily);
  this.lineAtlas = new LineAtlas(256, 512);
  this.crossTileSymbolIndex = new CrossTileSymbolIndex();

src/ui/events.js

@@ -778,6 +778,20 @@ export type MapEvent =
  */
  | 'sourcedataloading'
 
+ /**
+ * Fired when an icon or pattern needed by the style is missing. The missing image can
+ * be added with {@link Map#addImage} within this event listener callback to prevent the image from
+ * being skipped. This event can be used to dynamically generate icons and patterns.
+ *
+ * @event styleimagemissing
+ * @memberof Map
+ * @instance
+ * @property {string} id The id of the missing image.
+ *
+ * @see [Generate and add a missing icon to the map](https://mapbox.com/mapbox-gl-js/example/add-image-missing-generated/)
+ */
+ | 'styleimagemissing'
+
  /**
  * @event style.load
  * @memberof Map

test/unit/ui/map.test.js

@@ -1945,6 +1945,26 @@ test('Map', (t) => {
  t.end();
  });
 
+ t.test('map fires `styleimagemissing` for missing icons', (t) => {
+ const map = createMap(t);
+
+ const id = "missing-image";
+
+ let called;
+ map.on('styleimagemissing', e => {
+ map.addImage(e.id, {width: 1, height: 1, data: new Uint8Array(4)});
+ called = e.id;
+ });
+
+ t.notok(map.hasImage(id));
+
+ map.style.imageManager.getImages([id], () => {
+ t.equals(called, id);
+ t.ok(map.hasImage(id));
+ t.end();
+ });
+ });
+
  t.end();
 });