maplibre-gl 6.0.0 → 6.2.0

package/src/source/image_source.test.ts

@@ -1,16 +1,15 @@
-import {describe, beforeEach, test, expect, vi} from 'vitest';
+import {describe, beforeEach, afterEach, test, expect, vi, type Mock} from 'vitest';
 import {ImageSource} from './image_source.ts';
-import {Evented} from '../util/evented.ts';
-import {type IReadonlyTransform} from '../geo/transform_interface.ts';
 import {extend, MAX_TILE_ZOOM} from '../util/util.ts';
 import {type FakeServer, fakeServer} from 'nise';
-import {type RequestManager} from '../util/request_manager.ts';
-import {sleep, stubAjaxGetImage, waitForEvent} from '../util/test/util.ts';
+import {beforeMapTest, createMap, sleep, stubAjaxGetImage, waitForEvent} from '../util/test/util.ts';
 import {Tile} from '../tile/tile.ts';
 import {OverscaledTileID} from '../tile/tile_id.ts';
-import {type Texture} from '../webgl/texture.ts';
+import {ImageRequest} from '../util/image_request.ts';
+import type {Texture} from '../webgl/texture.ts';
 import type {ImageSourceSpecification} from '@maplibre/maplibre-gl-style-spec';
-import {MercatorTransform} from '../geo/projection/mercator_transform.ts';
+import type {MapSourceDataEvent} from '../ui/events.ts';
+import type {Map} from '../ui/map.ts';
 
 function createSource(options) {
     options = extend({
@@ -20,36 +19,23 @@ function createSource(options) {
     return new ImageSource('id', options, {} as any, options.eventedParent);
 }
 
-class StubMap extends Evented {
-    transform: IReadonlyTransform;
-    painter: any;
-    _requestManager: RequestManager;
-
-    constructor() {
-        super();
-        this.transform = new MercatorTransform();
-        this._requestManager = {
-            transformRequest: (url) => {
-                return {url};
-            }
-        } as any as RequestManager;
-        this.painter = {
-            context: {
-                gl: {}
-            }
-        };
-    }
-}
-
 describe('ImageSource', () => {
     stubAjaxGetImage(undefined);
     let server: FakeServer;
+    let map: Map;
 
     beforeEach(() => {
+        beforeMapTest();
         global.fetch = null;
         server = fakeServer.create();
         server.respondWith(new ArrayBuffer(1));
         server.respondWith('/missing-image.png', [404, {}, '']);
+        map = createMap({style: null});
+    });
+
+    afterEach(() => {
+        map.remove();
+        vi.restoreAllMocks();
     });
 
     test('constructor', () => {
@@ -65,33 +51,66 @@ describe('ImageSource', () => {
         source.on('dataloading', (e) => {
             expect(e.dataType).toBe('source');
         });
-        source.onAdd(new StubMap() as any);
+        source.onAdd(map);
         await sleep(0);
         server.respond();
         await sleep(0);
         expect(source.image).toBeTruthy();
     });
 
+    test('passes a live AbortController to ImageRequest when the source is aborted during an async transformRequest', async () => {
+        const source = createSource({url: '/image.png'});
+        let transformStarted: () => void;
+        const transformCalled = new Promise<void>((resolve) => {
+            transformStarted = resolve;
+        });
+        let releaseTransform: (params: {url: string}) => void;
+        map.setTransformRequest(() => {
+            transformStarted();
+            return new Promise<{url: string}>((resolve) => {
+                releaseTransform = resolve;
+            });
+        });
+        const image = {width: 1, height: 1} as ImageBitmap;
+        let requestController: AbortController;
+        let sourceControllerAtRequestTime: AbortController;
+        const getImageSpy = vi.spyOn(ImageRequest, 'getImage').mockImplementation(async (_request, abortController) => {
+            requestController = abortController;
+            sourceControllerAtRequestTime = source._request;
+            return {data: image};
+        });
+
+        source.onAdd(map);
+        await transformCalled; // load() is suspended in the transform
+        source.onRemove(); // the abort lands during that suspension
+        const loaded = waitForEvent(source, 'data', (e: MapSourceDataEvent) => e.sourceDataType === 'metadata');
+        releaseTransform({url: '/image.png'});
+        await loaded;
+
+        expect(getImageSpy).toHaveBeenCalledTimes(1);
+        // The request must carry the source's own live controller, so an abort
+        // arriving while it is in flight reaches exactly this request.
+        expect(requestController).toBeInstanceOf(AbortController);
+        expect(requestController).toBe(sourceControllerAtRequestTime);
+    });
+
     test('transforms url request', () => {
+        const transformRequest = vi.fn((url: string, _resourceType?: string) => ({url}));
         const source = createSource({url: '/image.png'});
-        const map = new StubMap() as any;
-        const spy = vi.spyOn(map._requestManager, 'transformRequest');
+        map.setTransformRequest(transformRequest);
         source.onAdd(map);
         server.respond();
-        expect(spy).toHaveBeenCalledTimes(1);
-        expect(spy.mock.calls[0][0]).toBe('/image.png');
-        expect(spy.mock.calls[0][1]).toBe('Image');
+        expect(transformRequest).toHaveBeenCalledTimes(1);
+        expect(transformRequest.mock.calls[0][0]).toBe('/image.png');
+        expect(transformRequest.mock.calls[0][1]).toBe('Image');
     });
 
     test('can asynchronously transform request', async () => {
         const source = createSource({url: '/image.png'});
-        const map = new StubMap() as any;
-        map._requestManager = {
-            transformRequest: async (url) => ({
-                url,
-                headers: {Authorization: 'Bearer token'}
-            })
-        };
+        map.setTransformRequest(async (url) => ({
+            url,
+            headers: {Authorization: 'Bearer token'}
+        }));
         const promise = source.once('data');
         source.onAdd(map);
         await sleep(0);
@@ -102,24 +121,23 @@ describe('ImageSource', () => {
     });
 
     test('updates url from updateImage', () => {
+        const transformRequest = vi.fn((url: string, _resourceType?: string) => ({url}));
         const source = createSource({url: '/image.png'});
-        const map = new StubMap() as any;
-        const spy = vi.spyOn(map._requestManager, 'transformRequest');
+        map.setTransformRequest(transformRequest);
         source.onAdd(map);
         server.respond();
-        expect(spy).toHaveBeenCalledTimes(1);
-        expect(spy.mock.calls[0][0]).toBe('/image.png');
-        expect(spy.mock.calls[0][1]).toBe('Image');
+        expect(transformRequest).toHaveBeenCalledTimes(1);
+        expect(transformRequest.mock.calls[0][0]).toBe('/image.png');
+        expect(transformRequest.mock.calls[0][1]).toBe('Image');
         source.updateImage({url: '/image2.png'});
         server.respond();
-        expect(spy).toHaveBeenCalledTimes(2);
-        expect(spy.mock.calls[1][0]).toBe('/image2.png');
-        expect(spy.mock.calls[1][1]).toBe('Image');
+        expect(transformRequest).toHaveBeenCalledTimes(2);
+        expect(transformRequest.mock.calls[1][0]).toBe('/image2.png');
+        expect(transformRequest.mock.calls[1][1]).toBe('Image');
     });
 
     test('sets coordinates', () => {
         const source = createSource({url: '/image.png'});
-        const map = new StubMap() as any;
         source.onAdd(map);
         server.respond();
         const beforeSerialized = source.serialize();
@@ -131,7 +149,6 @@ describe('ImageSource', () => {
 
     test('sets coordinates via updateImage', async () => {
         const source = createSource({url: '/image.png'});
-        const map = new StubMap() as any;
         source.onAdd(map);
         server.respond();
         const beforeSerialized = source.serialize();
@@ -150,7 +167,7 @@ describe('ImageSource', () => {
     test('fires data event when content is loaded', async () => {
         const source = createSource({url: '/image.png'});
         const promise = waitForEvent(source, 'data', (e) => e.dataType === 'source' && e.sourceDataType === 'content');
-        source.onAdd(new StubMap() as any);
+        source.onAdd(map);
         await sleep(0);
         server.respond();
         await promise;
@@ -160,7 +177,7 @@ describe('ImageSource', () => {
     test('fires data event when metadata is loaded', async () => {
         const source = createSource({url: '/image.png'});
         const promise = waitForEvent(source, 'data', (e) => e.dataType === 'source' && e.sourceDataType === 'metadata');
-        source.onAdd(new StubMap() as any);
+        source.onAdd(map);
         await sleep(0);
         server.respond();
         await expect(promise).resolves.toBeDefined();
@@ -170,7 +187,7 @@ describe('ImageSource', () => {
         const source = createSource({url: '/image.png'});
         const tile = new Tile(new OverscaledTileID(1, 0, 1, 0, 0), 512);
         const promise = waitForEvent(source, 'data', (e) => e.dataType === 'source' && e.sourceDataType === 'idle');
-        source.onAdd(new StubMap() as any);
+        source.onAdd(map);
         server.respond();
 
         source.tiles[String(tile.tileID.wrap)] = tile;
@@ -192,7 +209,6 @@ describe('ImageSource', () => {
     });
 
     test('allows using updateImage before initial image is loaded', async () => {
-        const map = new StubMap() as any;
         const source = createSource({url: '/image.png', eventedParent: map});
 
         // Suppress errors because we're aborting when updating.
@@ -208,7 +224,6 @@ describe('ImageSource', () => {
     });
 
     test('cancels request if updateImage is used', async () => {
-        const map = new StubMap() as any;
         const source = createSource({url: '/image.png', eventedParent: map});
 
         // Suppress errors because we're aborting.
@@ -223,7 +238,6 @@ describe('ImageSource', () => {
     });
 
     test('marks the source as loaded when the request has received a response', async () => {
-        const map = new StubMap() as any;
         const source = createSource({url: '/image.png', eventedParent: map});
 
         expect(source.loaded()).toBe(false);
@@ -248,7 +262,6 @@ describe('ImageSource', () => {
     });
 
     test('does not throw when updateImage is called while a request is pending', async () => {
-        const map = new StubMap() as any;
         const source = createSource({url: '/image.png', eventedParent: map});
 
         const errorHandler = vi.fn();
@@ -262,10 +275,75 @@ describe('ImageSource', () => {
         expect(errorHandler).not.toHaveBeenCalled();
     });
 
+    describe('updateImage with a decoded image', () => {
+        let source: ImageSource;
+        let transformRequest: Mock<(url: string, resourceType?: string) => any>;
+
+        beforeEach(() => {
+            transformRequest = vi.fn((url: string, _resourceType?: string) => ({url}));
+            map.setTransformRequest(transformRequest);
+            // Suppress errors from aborting the initial (never-responded) request.
+            map.on('error', () => {});
+            source = createSource({url: '/image.png', eventedParent: map});
+            // onAdd starts the initial load synchronously up to its first await, so
+            // this._request is set and transformRequest is called once. Clear that call
+            // so tests can assert the image path issues no further request.
+            source.onAdd(map);
+            transformRequest.mockClear();
+        });
+
+        test('sets the image directly without a network request and fires metadata', () => {
+            const handler = vi.fn();
+            source.on('data', handler);
+            const bitmap = new ImageBitmap();
+            const result = source.updateImage({image: bitmap});
+
+            expect(result).toBe(source);
+            // The image path must not trigger a request.
+            expect(transformRequest).not.toHaveBeenCalled();
+            expect(source.image).toBe(bitmap);
+            expect(source.loaded()).toBe(true);
+            const firedMetadata = handler.mock.calls.some(
+                ([e]) => e.dataType === 'source' && e.sourceDataType === 'metadata'
+            );
+            expect(firedMetadata).toBe(true);
+        });
+
+        test('resets the texture so the new image is uploaded on the next prepare', () => {
+            source.texture = {} as Texture;
+            source.updateImage({image: new ImageBitmap()});
+
+            expect(source.texture).toBeNull();
+        });
+
+        test('updates coordinates alongside the image', () => {
+            source.updateImage({
+                image: new ImageBitmap(),
+                coordinates: [[0, 0], [-1, 0], [-1, -1], [0, -1]]
+            });
+
+            expect(source.serialize().coordinates).toEqual([[0, 0], [-1, 0], [-1, -1], [0, -1]]);
+        });
+
+        test('cancels a pending request', () => {
+            const spy = vi.spyOn(source._request, 'abort');
+            source.updateImage({image: new ImageBitmap()});
+            expect(spy).toHaveBeenCalled();
+        });
+
+        test('accepts an ImageData instance', () => {
+            const imageData = new ImageData(1, 1);
+            source.updateImage({image: imageData});
+
+            expect(transformRequest).not.toHaveBeenCalled();
+            expect(source.image).toBe(imageData);
+            expect(source.loaded()).toBe(true);
+        });
+    });
+
     describe('terrainTileRanges', () => {
         test('sets tile ranges for all zoom levels', () => {
             const source = createSource({url: '/image.png'});
-            const map = new StubMap() as any;
             source.onAdd(map);
             server.respond();
             source.setCoordinates([[-10, 10], [10, 10], [10, -10], [-10, -10]]);
@@ -277,7 +355,6 @@ describe('ImageSource', () => {
 
         test('calculates tile ranges properly', () => {
             const source = createSource({url: '/image.png'});
-            const map = new StubMap() as any;
             source.onAdd(map);
             server.respond();
             source.setCoordinates([[11.39585,47.30074],[11.46585,47.30074],[11.46585,47.25074],[11.39585,47.25074]]);
@@ -317,7 +394,6 @@ describe('ImageSource', () => {
 
         test('calculates tile ranges for an image exceeds the world bounds - east', () => {
             const source = createSource({url: '/image.png'});
-            const map = new StubMap() as any;
             source.onAdd(map);
             server.respond();
             source.setCoordinates([[-180, 60], [270, 60], [270, -60], [-180, -60]]);
@@ -341,7 +417,6 @@ describe('ImageSource', () => {
 
         test('calculates tile ranges for an image exceeds the world bounds - west', () => {
             const source = createSource({url: '/image.png'});
-            const map = new StubMap() as any;
             source.onAdd(map);
             server.respond();
             source.setCoordinates([[120, 60], [-270, 60], [-270, -60], [120, -60]]);

package/src/source/image_source.ts

@@ -29,18 +29,34 @@ import {isAbortError} from '../util/abort_error.ts';
 export type Coordinates = [[number, number], [number, number], [number, number], [number, number]];
 
 /**
- * The options object for the {@link ImageSource.updateImage} method
+ * An already-decoded image that can be handed to an {@link ImageSource} directly,
+ * without a network request.
+ */
+export type ImageSourceImage = HTMLImageElement | HTMLCanvasElement | ImageBitmap | ImageData;
+
+/**
+ * The options object for the {@link ImageSource.updateImage} method.
+ *
+ * Provide exactly one of `url` (to load an image over the network) or `image`
+ * (an already-decoded image to display directly, without a network request).
  */
 export type UpdateImageOptions = {
     /**
-     * Required image URL.
+     * The image coordinates
+     */
+    coordinates?: Coordinates;
+} & ({
+    /**
+     * The image URL to load.
      */
     url: string;
+} | {
     /**
-     * The image coordinates
+     * An already-decoded image (`HTMLImageElement`, `HTMLCanvasElement`, `ImageBitmap` or `ImageData`)
+     * to display directly, without a network request.
      */
-    coordinates?: Coordinates;
-};
+    image: ImageSourceImage;
+});
 
 export type CanonicalTileRange = {
     minTileY: number;
@@ -96,6 +112,10 @@ export type CanonicalTileRange = {
  *    ]
  * })
  *
+ * // update with an already-decoded image (no network request)
+ * const bitmap = await createImageBitmap(myCanvas);
+ * mySource.updateImage({image: bitmap});
+ *
  * map.removeSource('some id');  // remove
  * ```
  */
@@ -118,7 +138,7 @@ export class ImageSource extends Evented<SourceEventType> implements Source {
     dispatcher: Dispatcher;
     map: Map;
     texture: Texture | null;
-    image: HTMLImageElement | ImageBitmap;
+    image: ImageSourceImage;
     tileID: CanonicalTileID;
     tileCoords: Point[];
     flippedWindingOrder: boolean = false;
@@ -150,9 +170,10 @@ export class ImageSource extends Evented<SourceEventType> implements Source {
 
         this.url = this.options.url;
 
+        const request = await this.map._requestManager.transformRequest(this.url, ResourceType.Image);
         this._request = new AbortController();
         try {
-            const image = await ImageRequest.getImage(await this.map._requestManager.transformRequest(this.url, ResourceType.Image), this._request);
+            const image = await ImageRequest.getImage(request, this._request);
             this._request = null;
             this._loaded = true;
 
@@ -177,21 +198,37 @@ export class ImageSource extends Evented<SourceEventType> implements Source {
     }
 
     /**
-     * Updates the image URL and, optionally, the coordinates. To avoid having the image flash after changing,
+     * Updates the image and, optionally, the coordinates. To avoid having the image flash after changing,
      * set the `raster-fade-duration` paint property on the raster layer to 0.
      *
+     * Provide exactly one of `url` (to fetch a new image over the network) or `image` (an
+     * already-decoded `HTMLImageElement`, `HTMLCanvasElement`, `ImageBitmap` or `ImageData` to
+     * display directly, without a network request).
+     *
      * @param options - The options object.
      */
     updateImage(options: UpdateImageOptions): this {
-        if (!options.url) {
-            return this;
-        }
-
         if (this._request) {
             this._request.abort();
             this._request = null;
         }
 
+        if ('image' in options) {
+            // Use the already-decoded image directly, skipping the network request.
+            this._loaded = true;
+            this.image = options.image;
+            if (options.coordinates) {
+                this.coordinates = options.coordinates;
+            }
+            this.texture = null;
+            this._finishLoading();
+            return this;
+        }
+
+        if (!options.url) {
+            return this;
+        }
+
         this.options.url = options.url;
         this.load(options.coordinates).finally(() => this.texture = null);
         return this;

package/src/source/raster_dem_tile_source.test.ts

@@ -1,4 +1,4 @@
-import {describe, beforeEach, afterEach, test, expect, vi, it} from 'vitest';
+import {describe, beforeEach, afterEach, test, expect, vi} from 'vitest';
 import {fakeServer, type FakeServer} from 'nise';
 import {RasterDEMTileSource} from './raster_dem_tile_source.ts';
 import {OverscaledTileID} from '../tile/tile_id.ts';
@@ -198,7 +198,7 @@ describe('RasterDEMTileSource', () => {
         ]);
     });
 
-    it('serializes options', () => {
+    test('serializes options', () => {
         const source = createSource({
             tiles: ['http://localhost:2900/raster-dem/{z}/{x}/{y}.png'],
             minzoom: 2,

package/src/source/raster_tile_source.test.ts

@@ -1,4 +1,4 @@
-import {describe, beforeEach, afterEach, test, expect, vi, it} from 'vitest';
+import {describe, beforeEach, afterEach, test, expect, vi} from 'vitest';
 import {RasterTileSource} from './raster_tile_source.ts';
 import {OverscaledTileID} from '../tile/tile_id.ts';
 import {RequestManager} from '../util/request_manager.ts';
@@ -216,15 +216,21 @@ describe('RasterTileSource', () => {
         expect(tile.state).toBe('loaded');
     });
 
-    test('supports updating tiles', () => {
+    test('supports updating tiles', async () => {
+        server.respondWith('/source.json', JSON.stringify({
+            minzoom: 0,
+            maxzoom: 22,
+            attribution: 'MapLibre',
+            tiles: ['http://example.com/{z}/{x}/{y}.png'],
+        }));
         const source = createSource({url: '/source.json'});
+
+        server.respondImmediately = true;
+        const promise = waitForEvent(source, 'data', (e: MapSourceDataEvent) => e.sourceDataType === 'metadata');
         source.setTiles(['http://example.com/{z}/{x}/{y}.png?updated=true']);
+        await promise;
 
-        source.on('data', (e) => {
-            if (e.sourceDataType === 'metadata') {
-                expect(source.tiles[0]).toBe('http://example.com/{z}/{x}/{y}.png?updated=true');
-            }
-        });
+        expect(source.tiles[0]).toBe('http://example.com/{z}/{x}/{y}.png?updated=true');
     });
 
     test('cancels TileJSON request if removed', async () => {
@@ -256,7 +262,7 @@ describe('RasterTileSource', () => {
 
         await waitForEvent(source, 'data', (e: MapSourceDataEvent) => e.sourceDataType === 'metadata');
 
-        expect(server.requests.length).toBe(2);
+        expect(server.requests).toHaveLength(2);
         expect(server.requests[0].aborted).toBe(true);
         expect(source.serialize()).toEqual({
             type: 'raster',
@@ -265,7 +271,7 @@ describe('RasterTileSource', () => {
         expect(errorHandler).not.toHaveBeenCalled();
     });
 
-    it('serializes options', () => {
+    test('serializes options', () => {
         const source = createSource({
             tiles: ['http://localhost:2900/raster/{z}/{x}/{y}.png'],
             minzoom: 2,
@@ -439,6 +445,55 @@ describe('RasterTileSource', () => {
         expect(expiryDataSpy).toHaveBeenCalledTimes(1);
     });
 
+    test('passes a live AbortController to ImageRequest when the tile is aborted during an async transformRequest', async () => {
+        let transformStarted: () => void;
+        const transformCalled = new Promise<void>((resolve) => {
+            transformStarted = resolve;
+        });
+        let releaseTransform: (params: {url: string}) => void;
+        const source = createSource({
+            tiles: ['http://example.com/{z}/{x}/{y}.png']
+        }, (url, type) => {
+            if (type !== 'Tile') return {url};
+            transformStarted();
+            return new Promise<{url: string}>((resolve) => {
+                releaseTransform = resolve;
+            });
+        });
+        source.tiles = ['http://example.com/{z}/{x}/{y}.png'];
+
+        const image = {width: 256, height: 256} as ImageBitmap;
+        let requestController: AbortController;
+        let tileControllerAtRequestTime: AbortController;
+        const getImageSpy = vi.spyOn(ImageRequest, 'getImage').mockImplementation(async (_request, abortController) => {
+            requestController = abortController;
+            tileControllerAtRequestTime = tile.abortController;
+            return {data: image};
+        });
+        source.map.painter = {
+            context: {gl: {}},
+            getTileTexture: () => ({update: vi.fn()})
+        } as any;
+
+        const tile = {
+            tileID: new OverscaledTileID(10, 0, 10, 5, 5),
+            state: 'loading',
+            setExpiryData() {}
+        } as any as Tile;
+
+        const loadPromise = source.loadTile(tile);
+        await transformCalled; // loadTile is suspended in the transform
+        await source.abortTile(tile); // the abort lands during that suspension
+        releaseTransform({url: 'http://example.com/10/5/5.png'});
+        await expect(loadPromise).resolves.toBeUndefined();
+
+        expect(getImageSpy).toHaveBeenCalledTimes(1);
+        // The request must carry the tile's own live controller, so an abort
+        // arriving while it is in flight reaches exactly this request.
+        expect(requestController).toBeInstanceOf(AbortController);
+        expect(requestController).toBe(tileControllerAtRequestTime);
+    });
+
     test('does not throw when tile is aborted', async () => {
         const source = createSource({
             minzoom: 0,

package/src/source/raster_tile_source.ts

@@ -206,10 +206,11 @@ export class RasterTileSource extends Evented<SourceEventType> implements Source
         const url = tile.tileID.canonical.url(this.tiles, this.map.getPixelRatio(), this.scheme);
         const premultiply = this._premultiplyAlpha;
         const imageBitmapOptions = premultiply ? undefined : {premultiplyAlpha: 'none'} as const;
+        const request = await this.map._requestManager.transformRequest(url, ResourceType.Tile);
         tile.abortController = new AbortController();
         try {
             const response = await ImageRequest.getImage(
-                await this.map._requestManager.transformRequest(url, ResourceType.Tile),
+                request,
                 tile.abortController,
                 this.map._refreshExpiredTiles,
                 imageBitmapOptions