add styleimagemissing event for on-demand images

[ansis]

This is the first of several dynamic icon prs.

The event gets fired when a layer needs an image that the map doesn't have. The developer has a chance to listen for this event and add an image within the callback in order to have it included.

This event can be used to dynamically generate icons based on feature properties.

fix #7587

map.on('styleimageneeded', function(e) {
    var image = generateImage(e.id);
    map.addImage(e.id, image);
});

See the committed add-image-missing-generated example for a full version.

Naming

I'm pretty ok with styleimageneeded. Other alternatives were:

• styleimagemissing
• imageneeded
• imagemissing

Do you prefer any of these?

Launch Checklist

• briefly describe the changes in this PR
• write tests for all new functionality
• document any changes to public APIs
• [n/a] post benchmark scores
• manually test the debug page

[ryanhamley]

I think this looks great. Just a couple nits on language.

I don't have a strong preference on the name of the event. styleimageneeded and styleimagemissing both work for me. If you want to include a warning as well, that's probably not a bad idea, but otherwise 👍

[ryanhamley]

Maybe better to be explicit here -> within the event listener callback

[ansis]

yep, good idea!

[ryanhamley]

Nit: in the map that was generated at runtime, "that" appears to reference "map". Maybe something like Dynamically generate a missing icon at runtime and add it to the map?

[ansis]

yep, that's better. Thanks!

[asheemmamoowala]

The example in this PR is 💯!

I think the styleimage prefix is good for distinguishing from source images (for image or raster sources). I like missing vs needed because it describes the event better. styleimagenotfound is one more for the naming 🎩.

[mourner]

👍 No strong preference but styleimagemissing sounds good to me.

[ansis]

Thanks for the suggestions and feedback. I'll merge this as styleimagemissing

[joewoodhouse]

#6231 for me renders this feature unusable (though I love the idea of it). Currently that bug still exists for me in my use-case - the icons never properly render at the initial zoom level when I add them via the styleimagemissing event. As the initial reports say, they seem to mostly render fine at all other zoom levels, which makes me think this must surely just be a bug that needs fixing? Even if I heavily delay adding the layers that have the missing icons, they still don't render properly.

[mourner]

@joewoodhouse can you submit a new bug report with a minimal reproducible test case for this (e.g. using JSFiddle)?

[joewoodhouse]

@mourner I've created #8335 which includes a codepen to recreate the issue.