[lucaswoj]

fix #7857

Today the recommended way to animate an icon is a StyleImageInterface#render callback that rewrites the icon's pixels every frame. MapLibre reprocesses those pixels on the CPU and re-uploads the whole icon to the GPU. That looks fine in a demo, but in a real app where many effects compete for frame time, a few animated icons cause real lag, especially on lower-powered phones.

This PR lets a StyleImageInterface hand over a {renderWithWebGL} callback as its data, in place of an array of pixels. Such an image renders straight into its slot of the shared icon atlas on the GPU:

interface StyleImageInterface {
    width: number;
    height: number;
    data: Uint8Array | Uint8ClampedArray | StyleImageWebGLData;
    render?: () => boolean;
    onAdd?: (map: Map, id: string) => void;
    onRemove?: () => void;
}

type StyleImageWebGLData = {
    renderWithWebGL: (target: StyleImageWebGLTarget) => void;
};

type StyleImageWebGLTarget = {
    gl: WebGL2RenderingContext;
    texture: WebGLTexture;
    x: number;
    y: number;
    width: number;
    height: number;
};

An image asks to be rendered again by returning true from render, the same signal the existing StyleImageInterface uses to commit new pixels. renderWithWebGL is the image's counterpart to CustomLayerInterface.render, and receives its GL context in the same state. It is also called before the first frame the image is used in, and again for each atlas holding a slot this image has never rendered into, so one change can mean several calls with different targets.

This can be used to show icons driven by animated images, videos, an external canvas, or shaders. The new animate-an-icon-on-the-gpu example renders a triangle whose corner hues cycle once a second, computed in a vertex shader instead of a JS pixel loop.

Performance

I'm working on a plugin that decodes a GIF, animated WebP, APNG or animated AVIF; uploads every frame to the GPU once packed into a grid; and advances a frame with a copyTexSubImage2D into the icon's atlas slot. No per-frame CPU work, no upload, no atlas repack. I'll publish it separately.

50 icons, 256px, 8 frames, one frame change per render, Apple M4 Max, headless Chrome:

how the icon animates	cost per frame
StyleImageInterface#render rewriting pixels	18.0 ms
StyleImageWebGLData#renderWithWebGL	0.64 ms

About 28x here, and more on phones where the CPU work is relatively more expensive.

Launch Checklist

• Confirm your changes do not include backports from Mapbox projects (unless with compliant license) - if you are not sure about this, please ask!
• Briefly describe the changes in this PR.
• Link to related issues.
• Include before/after visuals or gifs if this PR includes visual changes.
• Write tests for all new functionality.
• Document any changes to public APIs.
• Post benchmark scores.
• Add an entry to CHANGELOG.md under the ## main section.
• Confirm you have read our AI policy here.

Assisted-By: Claude Opus 5

[codecov]

Codecov Report

❌ Patch coverage is 92.50000% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 93.59%. Comparing base (f950bf6) to head (bc6c02d).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
src/ui/map.ts	72.72%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7954      +/-   ##
==========================================
+ Coverage   93.42%   93.59%   +0.16%     
==========================================
  Files         291      291              
  Lines       24631    24655      +24     
  Branches     6490     6498       +8     
==========================================
+ Hits        23012    23075      +63     
+ Misses       1619     1580      -39     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[lucaswoj]

• Fix the idle event
• Ensure animations survive WebGL context loss
• Validate all frame sizes match
• Fix crash when passing addImage(id, [])
• Guard against extrmely large aniation texture sizes
• Add tests
• Add docs

[lucaswoj]

Status update: I'm heading into the backcountry and offline through Tuesday 7/28. I'll pick this back up Wednesday.

[lucaswoj]

This is ready for review

[HarelM]

Can you add a short html example using this new API? Add @example maybe in the interface signature too?

This looks very specific and concise, which is good.

Can you share maybe what other alternatives you have considered and rejected to solve this?

I'm trying to get the bigger picture here.

[HarelM]

Added a few commets, see if you can reduce some in method comments and move those to tsdocs, also reduce comments inside tests as much as possible.

[lucaswoj]

This is ready for another round of review

[HarelM]

Added a minor comment.
Looks good overall.
Let me know how you want to proceed.

[lucaswoj]

Just did a final manual check on the example page and some of my prototype plugins. All looks good to me! I think this is ready to 🚢 . Thanks for the review.

[HarelM]

Thanks!! It will probably take a week or two to release, I hope that's fine.