maplibre-gl 6.2.0 → 6.4.0

package/src/render/image_manager.test.ts

@@ -0,0 +1,111 @@
+import {test, expect, vi} from 'vitest';
+import {ImageManager} from './image_manager.ts';
+import {RGBAImage} from '../util/image.ts';
+
+import type {StyleImage} from '../style/style_image.ts';
+
+function webGLImage(render?: () => boolean): StyleImage {
+    return {
+        data: new RGBAImage({width: 2, height: 2}),
+        version: 0,
+        pixelRatio: 1,
+        sdf: false,
+        isWebGLImage: true,
+        userImage: {width: 2, height: 2, data: {renderWithWebGL: vi.fn()}, render}
+    };
+}
+
+function styleImage(size: number = 2): StyleImage {
+    return {data: new RGBAImage({width: size, height: size}), pixelRatio: 1, sdf: false};
+}
+
+/** An image of a sprite that was never rendered, so its pixels are still in the sprite sheet */
+function undecodedSpriteImage(size: number): StyleImage {
+    return {
+        data: null,
+        pixelRatio: 1,
+        sdf: false,
+        spriteData: {width: size, height: size, x: 0, y: 0, context: null}
+    };
+}
+
+test('a WebGL image owes every atlas a render as soon as it is added, even without a render callback', () => {
+    const manager = new ImageManager();
+    const updateVersion = manager.updateVersion;
+    manager.addImage('webgl', webGLImage());
+
+    expect(manager.getImage('webgl').version).toBe(1);
+    expect(manager.updateVersion).toBe(updateVersion + 1);
+});
+
+test('a WebGL image is re-rendered when its render callback reports a change', () => {
+    const manager = new ImageManager();
+    manager.addImage('webgl', webGLImage(() => true));
+    const version = manager.getImage('webgl').version;
+
+    manager.beginFrame();
+    manager.dispatchRenderCallbacks(['webgl']);
+
+    expect(manager.getImage('webgl').version).toBe(version + 1);
+});
+
+test('a WebGL image is left alone when its render callback reports no change', () => {
+    const manager = new ImageManager();
+    manager.addImage('webgl', webGLImage(() => false));
+    const version = manager.getImage('webgl').version;
+
+    manager.beginFrame();
+    manager.dispatchRenderCallbacks(['webgl']);
+
+    expect(manager.getImage('webgl').version).toBe(version);
+});
+
+test('a render callback runs once per frame, however many atlases ask for it', () => {
+    const manager = new ImageManager();
+    const render = vi.fn(() => false);
+    manager.addImage('webgl', webGLImage(render));
+
+    manager.beginFrame();
+    manager.dispatchRenderCallbacks(['webgl']);
+    manager.dispatchRenderCallbacks(['webgl']);
+    expect(render).toHaveBeenCalledTimes(1);
+
+    manager.beginFrame();
+    manager.dispatchRenderCallbacks(['webgl']);
+    expect(render).toHaveBeenCalledTimes(2);
+});
+
+test('removing an image that is not there leaves the others alone', () => {
+    const manager = new ImageManager();
+    manager.addImage('kept', styleImage());
+
+    manager.removeImage('neverAdded');
+
+    expect(manager.listImages()).toEqual(['kept']);
+});
+
+test('the images a sprite brought in are removed with it, and reported as removed', () => {
+    const manager = new ImageManager();
+    manager.setSpriteImages('default', {fromSprite: styleImage(), alsoFromSprite: styleImage()});
+    manager.addImage('addedAtRuntime', styleImage());
+
+    expect(manager.removeSpriteImages('default')).toEqual(['fromSprite', 'alsoFromSprite']);
+    expect(manager.listImages()).toEqual(['addedAtRuntime']);
+    expect(manager.removeSpriteImages('default')).toEqual([]);
+});
+
+test('updateImage rejects an image of a different size than the one it replaces', () => {
+    const manager = new ImageManager();
+    manager.addImage('image', styleImage(2));
+
+    expect(() => manager.updateImage('image', styleImage(4))).toThrow(/size mismatch between old image \(2x2\) and new image \(4x4\)/);
+    expect(() => manager.updateImage('image', styleImage(2))).not.toThrow();
+});
+
+test('updateImage sizes up a sprite image that was never decoded without decoding it', () => {
+    const manager = new ImageManager();
+    manager.addImage('image', undecodedSpriteImage(2));
+
+    expect(() => manager.updateImage('image', styleImage(4))).toThrow(/size mismatch between old image \(2x2\) and new image \(4x4\)/);
+    expect(() => manager.updateImage('image', styleImage(2))).not.toThrow();
+});

package/src/render/image_manager.ts

@@ -1,49 +1,32 @@
-/* eslint-disable key-spacing */
-import potpack from 'potpack';
-
 import {ErrorEvent, Evented} from '../util/evented.ts';
 import {MapStyleImageMissingEvent} from '../ui/events.ts';
 import {RGBAImage} from '../util/image.ts';
-import {ImagePosition} from './image_atlas.ts';
-import {Texture} from '../webgl/texture.ts';
 import {renderStyleImage} from '../style/style_image.ts';
 import {warnOnce} from '../util/util.ts';
 
 import type {StyleImage} from '../style/style_image.ts';
-import type {Context} from '../webgl/context.ts';
-import type {PotpackBox} from 'potpack';
 import type {GetImagesResponse} from '../util/actor_messages.ts';
 
 export type MissingImageRequestHandler = (id: string) => void | Promise<void>;
 
-type Pattern = {
-    bin: PotpackBox;
-    position: ImagePosition;
+type ImageManagerEventType = {
+    error: ErrorEvent;
+    styleimagemissing: MapStyleImageMissingEvent;
 };
 
 /**
- * When copied into the atlas texture, image data is padded by one pixel on each side. Icon
- * images are padded with fully transparent pixels, while pattern images are padded with a
- * copy of the image data wrapped from the opposite side. In both cases, this ensures the
- * correct behavior of GL_LINEAR texture sampling mode.
- */
-const padding = 1;
-
-/**
- * ImageManager does three things:
- *
- * 1. Tracks requests for icon images from tile workers and sends responses when the requests are fulfilled.
- * 2. Builds a texture atlas for pattern images.
- * 3. Rerenders renderable images once per frame
- *
- * These are disparate responsibilities and should eventually be handled by different classes. When we implement
- * data-driven support for `*-pattern`, we'll likely use per-bucket pattern atlases, and that would be a good time
- * to refactor this.
+ * Owns every image of the style - the ones the sprites bring in as well as the ones added at
+ * runtime - and tracks requests for them from the tile workers, sending responses when the
+ * requests are fulfilled.
 */
-export class ImageManager extends Evented {
-    images: {[_: string]: StyleImage};
-    updatedImages: {[_: string]: boolean};
-    callbackDispatchedThisFrame: {[_: string]: boolean};
+export class ImageManager extends Evented<ImageManagerEventType> {
+    images: Record<string, StyleImage>;
+    /**
+     * Incremented on every {@link ImageManager.updateImage} call. {@link ImageAtlas} instances
+     * compare it against the value they last patched against, so that a tile whose atlas is up to
+     * date can skip its patching work entirely.
+     */
+    updateVersion: number;
     loaded: boolean;
     /**
      * This is used to track requests for images that are not yet available. When the image is loaded,
@@ -54,40 +37,37 @@ export class ImageManager extends Evented {
         promiseResolve: (value: GetImagesResponse | PromiseLike<GetImagesResponse>) => void;
     }>;
     missingImageResolver: MissingImageRequestHandler | null;
-
-    patterns: {[_: string]: Pattern};
-    atlasImage: RGBAImage;
-    atlasTexture: Texture;
-    dirty: boolean;
+    /**
+     * The images whose `render` callback already ran in the current frame. A given image usually
+     * sits in the atlas of several tiles, so it would otherwise be asked to re-render once per
+     * tile that holds it.
+     */
+    private _renderCallbacksDispatchedThisFrame: Record<string, boolean>;
+    /**
+     * The ids of the images each sprite has brought in, keyed by sprite id, so that they can be
+     * removed again when that sprite is reloaded or removed.
+     */
+    private _spriteImagesIds: Record<string, string[]>;
+    /** Cached result of {@link ImageManager.listImages}, invalidated whenever an image is added or removed */
+    private _imagesIds: string[] | null;
 
     constructor() {
         super();
         this.images = {};
-        this.updatedImages = {};
-        this.callbackDispatchedThisFrame = {};
+        this.updateVersion = 0;
         this.loaded = false;
         this.requestors = [];
         this.missingImageResolver = null;
-
-        this.patterns = {};
-        this.atlasImage = new RGBAImage({width: 1, height: 1});
-        this.dirty = true;
+        this._spriteImagesIds = {};
+        this._imagesIds = null;
+        this._renderCallbacksDispatchedThisFrame = {};
     }
 
     destroy(): void {
-        // Destroy atlas texture if it exists
-        if (this.atlasTexture) {
-            this.atlasTexture.destroy();
-            this.atlasTexture = null;
-        }
-        // Remove all images and patterns
         for (const id of Object.keys(this.images)) {
             this.removeImage(id);
         }
-
-        this.patterns = {};
-        this.atlasImage = new RGBAImage({width: 1, height: 1});
-        this.dirty = true;
+        this._spriteImagesIds = {};
     }
     isLoaded(): boolean {
         return this.loaded;
@@ -131,6 +111,8 @@ export class ImageManager extends Evented {
         if (this.images[id]) throw new Error(`Image id ${id} already exist, use updateImage instead`);
         if (this._validate(id, image)) {
             this.images[id] = image;
+            this._imagesIds = null;
+            if (image.isWebGLImage) this.updateImage(id, image, false);
         }
     }
 
@@ -176,28 +158,120 @@ export class ImageManager extends Evented {
         return content[3] >= content[1];
     }
 
+    /**
+     * Replaces an image that is already known under this id, bumping its version so that the
+     * atlases holding it notice.
+     *
+     * The old record is read directly rather than through {@link ImageManager.getImage}, which
+     * would force a synchronous decode of the sprite data of the very image being replaced. Its
+     * size therefore comes from whichever of the two the pixels are still in, since an image that
+     * came from a sprite and was never rendered has not been decoded yet, and its version is
+     * defaulted, since images start out without one.
+     *
+     * @param validate - whether to reject an image of a different size than the one it replaces
+     */
     updateImage(id: string, image: StyleImage, validate: boolean = true): void {
-        const oldImage = this.getImage(id);
-        if (validate && (oldImage.data.width !== image.data.width || oldImage.data.height !== image.data.height)) {
-            throw new Error(`size mismatch between old image (${oldImage.data.width}x${oldImage.data.height}) and new image (${image.data.width}x${image.data.height}).`);
+        const oldImage = this.images[id];
+        if (validate) {
+            const oldData = oldImage.data || oldImage.spriteData;
+            if (oldData.width !== image.data.width || oldData.height !== image.data.height) {
+                throw new Error(`size mismatch between old image (${oldData.width}x${oldData.height}) and new image (${image.data.width}x${image.data.height}).`);
+            }
         }
-        image.version = oldImage.version + 1;
+        image.version = (oldImage.version ?? 0) + 1;
         this.images[id] = image;
-        this.updatedImages[id] = true;
+        this.updateVersion++;
     }
 
     removeImage(id: string): void {
         const image = this.images[id];
+        if (!image) return;
         delete this.images[id];
-        delete this.patterns[id];
+        this._imagesIds = null;
 
         if (image.userImage?.onRemove) {
             image.userImage.onRemove();
         }
     }
 
+    /**
+     * @returns the ids of every image currently held, sprite images and runtime ones alike. The
+     * returned array is shared between callers and must not be modified.
+     */
     listImages(): string[] {
-        return Object.keys(this.images);
+        this._imagesIds ??= Object.keys(this.images);
+        return this._imagesIds;
+    }
+
+    /**
+     * Images of the `default` sprite keep their plain id, the ones of any other sprite are
+     * namespaced by their sprite's id.
+     */
+    private _getSpriteImageId(spriteId: string, imageId: string): string {
+        return spriteId === 'default' ? imageId : `${spriteId}:${imageId}`;
+    }
+
+    /**
+     * Takes over the images of a single sprite: adds the new ones, updates the ones that are
+     * already known, and removes the ones that a previous load of this same sprite had brought in
+     * but that are not part of it anymore.
+     *
+     * @param spriteId - the id of the sprite the images belong to
+     * @param images - the sprite's images, keyed by their id within the sprite
+     * @returns the ids of the images that this sprite now provides, and the ids of the ones that
+     * were removed because they are no longer part of it
+     */
+    setSpriteImages(spriteId: string, images: Record<string, StyleImage>): {loaded: string[]; removed: string[]} {
+        const previousIds = this._spriteImagesIds[spriteId] ?? [];
+        const loaded: string[] = [];
+
+        for (const id in images) {
+            const imageId = this._getSpriteImageId(spriteId, id);
+            loaded.push(imageId);
+
+            if (imageId in this.images) {
+                this.updateImage(imageId, images[id], false);
+            } else {
+                this.addImage(imageId, images[id]);
+            }
+        }
+
+        const loadedIds = new Set(loaded);
+        const removed = previousIds.filter(imageId => !loadedIds.has(imageId));
+        for (const imageId of removed) {
+            this.removeImage(imageId);
+        }
+
+        this._spriteImagesIds[spriteId] = loaded;
+        return {loaded, removed};
+    }
+
+    /**
+     * Removes all the images a single sprite has brought in.
+     * @returns the ids of the removed images
+     */
+    removeSpriteImages(spriteId: string): string[] {
+        const removed = this._spriteImagesIds[spriteId] ?? [];
+        for (const imageId of removed) {
+            this.removeImage(imageId);
+        }
+
+        delete this._spriteImagesIds[spriteId];
+        return removed;
+    }
+
+    /**
+     * Removes the images of every sprite, leaving the images added at runtime alone.
+     * @returns the ids of the removed images
+     */
+    removeAllSpriteImages(): string[] {
+        const removed = Object.values(this._spriteImagesIds).flat();
+        for (const imageId of removed) {
+            this.removeImage(imageId);
+        }
+
+        this._spriteImagesIds = {};
+        return removed;
     }
 
     setMissingImageResolver(resolver: MissingImageRequestHandler | null): void {
@@ -231,7 +305,7 @@ export class ImageManager extends Evented {
         const resolver = this.missingImageResolver;
 
         if (resolver) {
-            await Promise.all(Array.from(unresolvedIds, (id) => resolver(id)));
+            await Promise.allSettled(Array.from(unresolvedIds, (id) => resolver(id)));
         }
 
         const response: GetImagesResponse = {};
@@ -252,7 +326,8 @@ export class ImageManager extends Evented {
                     content: image.content,
                     textFitWidth: image.textFitWidth,
                     textFitHeight: image.textFitHeight,
-                    hasRenderCallback: Boolean(image.userImage?.render)
+                    hasRenderCallback: Boolean(image.userImage?.render),
+                    isWebGLImage: image.isWebGLImage
                 };
             }
         }
@@ -265,94 +340,18 @@ export class ImageManager extends Evented {
         return response;
     }
 
-    // Pattern stuff
-
-    getPixelSize(): {width: number; height: number} {
-        const {width, height} = this.atlasImage;
-        return {width, height};
-    }
-
-    getPattern(id: string): ImagePosition {
-        const pattern = this.patterns[id];
-
-        const image = this.getImage(id);
-        if (!image) {
-            return null;
-        }
-
-        // eslint-disable-next-line @typescript-eslint/prefer-optional-chain -- pattern?.position.version would be undefined when pattern is nullish, making undefined === undefined true
-        if (pattern && pattern.position.version === image.version) {
-            return pattern.position;
-        }
-
-        if (!pattern) {
-            const w = image.data.width + padding * 2;
-            const h = image.data.height + padding * 2;
-            const bin = {w, h, x: 0, y: 0};
-            const position = new ImagePosition(bin, image);
-            this.patterns[id] = {bin, position};
-        } else {
-            pattern.position.version = image.version;
-        }
-
-        this._updatePatternAtlas();
-
-        return this.patterns[id].position;
-    }
-
-    bind(context: Context): void {
-        const gl = context.gl;
-        if (!this.atlasTexture) {
-            this.atlasTexture = new Texture(context, this.atlasImage, gl.RGBA);
-        } else if (this.dirty) {
-            this.atlasTexture.update(this.atlasImage);
-            this.dirty = false;
-        }
-
-        this.atlasTexture.bind(gl.LINEAR, gl.CLAMP_TO_EDGE);
-    }
-
-    _updatePatternAtlas(): void {
-        const bins = [];
-        for (const id in this.patterns) {
-            bins.push(this.patterns[id].bin);
-        }
-
-        const {w, h} = potpack(bins);
-
-        const dst = this.atlasImage;
-        dst.resize({width: w || 1, height: h || 1});
-
-        for (const id in this.patterns) {
-            const {bin} = this.patterns[id];
-            const x = bin.x + padding;
-            const y = bin.y + padding;
-            const src = this.getImage(id).data;
-            const w = src.width;
-            const h = src.height;
-
-            RGBAImage.copy(src, dst, {x: 0, y: 0}, {x, y}, {width: w, height: h});
-
-            // Add 1 pixel wrapped padding on each side of the image.
-            RGBAImage.copy(src, dst, {x: 0, y: h - 1}, {x, y: y - 1}, {width: w, height: 1}); // T
-            RGBAImage.copy(src, dst, {x: 0, y:     0}, {x, y: y + h}, {width: w, height: 1}); // B
-            RGBAImage.copy(src, dst, {x: w - 1, y: 0}, {x: x - 1, y}, {width: 1, height: h}); // L
-            RGBAImage.copy(src, dst, {x: 0,     y: 0}, {x: x + w, y}, {width: 1, height: h}); // R
-        }
-
-        this.dirty = true;
-    }
-
     beginFrame(): void {
-        this.callbackDispatchedThisFrame = {};
+        this._renderCallbacksDispatchedThisFrame = {};
     }
 
+    /**
+     * Re-renders the images among `ids` that were added with a `render` callback (see
+     * `StyleImageInterface`), at most once per frame each.
+     */
     dispatchRenderCallbacks(ids: string[]): void {
         for (const id of ids) {
-
-            // the callback for the image was already dispatched for a different frame
-            if (this.callbackDispatchedThisFrame[id]) continue;
-            this.callbackDispatchedThisFrame[id] = true;
+            if (this._renderCallbacksDispatchedThisFrame[id]) continue;
+            this._renderCallbacksDispatchedThisFrame[id] = true;
 
             const image = this.getImage(id);
             if (!image) warnOnce(`Image with ID: "${id}" was not found`);

package/src/render/painter.ts

@@ -29,6 +29,7 @@ import type {StyleLayer} from '../style/style_layer.ts';
 import type {CrossFaded} from '../style/properties.ts';
 import type {LineAtlas} from './line_atlas.ts';
 import type {ImageManager} from './image_manager.ts';
+import type {PatternAtlas} from './pattern_atlas.ts';
 import type {GlyphManager} from './glyph_manager.ts';
 import type {VertexBuffer} from '../webgl/vertex_buffer.ts';
 import type {IndexBuffer} from '../webgl/index_buffer.ts';
@@ -140,6 +141,7 @@ export class Painter {
     options: PainterOptions;
     lineAtlas: LineAtlas;
     imageManager: ImageManager;
+    patternAtlas: PatternAtlas;
     glyphManager: GlyphManager;
     depthRangeFor3D: DepthRangeType;
     opaquePassCutoff: number;
@@ -518,6 +520,7 @@ export class Painter {
 
         this.lineAtlas = style.lineAtlas;
         this.imageManager = style.imageManager;
+        this.patternAtlas = style.patternAtlas;
         this.glyphManager = style.glyphManager;
 
         this.symbolFadeChange = style.placement.symbolFadeChange(now());
@@ -807,8 +810,8 @@ export class Painter {
     isPatternMissing(image?: CrossFaded<ResolvedImage> | null): boolean {
         if (!image) return false;
         if (!image.from || !image.to) return true;
-        const imagePosA = this.imageManager.getPattern(image.from.toString());
-        const imagePosB = this.imageManager.getPattern(image.to.toString());
+        const imagePosA = this.patternAtlas.getPattern(image.from.toString());
+        const imagePosB = this.patternAtlas.getPattern(image.to.toString());
         return !imagePosA || !imagePosB;
     }
 
@@ -857,18 +860,7 @@ export class Painter {
      * in custom layers.
      */
     setCustomLayerDefaults(): void {
-        // Prevent custom layers from unintentionally modify the last VAO used.
-        // All other state is state is restored on it's own, but for VAOs it's
-        // simpler to unbind so that we don't have to track the state of VAOs.
-        this.context.unbindVAO();
-
-        // The default values for this state is meaningful and often expected.
-        // Leaving this state dirty could cause a lot of confusion for users.
-        this.context.cullFace.setDefault();
-        this.context.activeTexture.setDefault();
-        this.context.pixelStoreUnpack.setDefault();
-        this.context.pixelStoreUnpackPremultiplyAlpha.setDefault();
-        this.context.pixelStoreUnpackFlipY.setDefault();
+        this.context.setCustomLayerDefaults();
     }
 
     /*

package/src/render/pattern_atlas.test.ts

@@ -0,0 +1,131 @@
+import {describe, expect, test, vi, beforeEach} from 'vitest';
+import {ImageManager} from './image_manager.ts';
+import {PatternAtlas} from './pattern_atlas.ts';
+import {Context} from '../webgl/context.ts';
+import {Texture} from '../webgl/texture.ts';
+import {createNullGL} from '../util/test/null_gl.ts';
+import {RGBAImage} from '../util/image.ts';
+
+import type {StyleImage} from '../style/style_image.ts';
+
+const PADDING_ON_EACH_SIDE = 2;
+const sizeInAtlas = (size: number) => ({width: size + PADDING_ON_EACH_SIDE, height: size + PADDING_ON_EACH_SIDE});
+
+function createStyleImage(size: number, fill: number = 0): StyleImage {
+    const data = new Uint8Array(size * size * 4).fill(fill);
+    return {
+        data: new RGBAImage({width: size, height: size}, data),
+        pixelRatio: 1,
+        sdf: false
+    };
+}
+
+describe('PatternAtlas', () => {
+    let imageManager: ImageManager;
+    let patternAtlas: PatternAtlas;
+    let context: Context;
+
+    beforeEach(() => {
+        vi.restoreAllMocks();
+        imageManager = new ImageManager();
+        patternAtlas = new PatternAtlas(imageManager);
+        context = new Context(createNullGL());
+    });
+
+    test('packs an image into a slot padded by one pixel on each side, and keeps handing back its position while it does not change', () => {
+        imageManager.addImage('pattern', createStyleImage(4));
+
+        const position = patternAtlas.getPattern('pattern');
+
+        expect(position.displaySize).toEqual([4, 4]);
+        expect(patternAtlas.getPixelSize()).toEqual(sizeInAtlas(4));
+        expect(patternAtlas.getPattern('pattern')).toBe(position);
+    });
+
+    test('re-packs the slot when a sprite reload replaces the image with a bigger one', () => {
+        imageManager.addImage('pattern', createStyleImage(4));
+        patternAtlas.getPattern('pattern');
+
+        imageManager.updateImage('pattern', createStyleImage(8), false);
+
+        expect(patternAtlas.getPattern('pattern').displaySize).toEqual([8, 8]);
+        expect(patternAtlas.getPixelSize()).toEqual(sizeInAtlas(8));
+    });
+
+    test('re-packs the slot when the image is removed and another one is added under the same id, even though neither carries a version', () => {
+        imageManager.addImage('pattern', createStyleImage(4));
+        const positionOfRemovedImage = patternAtlas.getPattern('pattern');
+
+        imageManager.removeImage('pattern');
+        imageManager.addImage('pattern', createStyleImage(8, 255));
+
+        const position = patternAtlas.getPattern('pattern');
+        expect(position).not.toBe(positionOfRemovedImage);
+        expect(position.displaySize).toEqual([8, 8]);
+    });
+
+    test('keeps the slot of an image that was updated in place, as an animated pattern is, and follows its version', () => {
+        const image = createStyleImage(4);
+        imageManager.addImage('pattern', image);
+        const position = patternAtlas.getPattern('pattern');
+
+        imageManager.updateImage('pattern', image, false);
+
+        expect(patternAtlas.getPattern('pattern')).toBe(position);
+        expect(position.version).toBe(image.version);
+    });
+
+    test('returns null for an image that was removed, and reclaims its slot on the next re-packing', () => {
+        imageManager.addImage('removedPattern', createStyleImage(4));
+        imageManager.addImage('keptPattern', createStyleImage(4));
+        patternAtlas.getPattern('removedPattern');
+        patternAtlas.getPattern('keptPattern');
+
+        imageManager.removeImage('removedPattern');
+
+        expect(patternAtlas.getPattern('removedPattern')).toBeNull();
+
+        imageManager.updateImage('keptPattern', createStyleImage(4), false);
+        expect(patternAtlas.getPattern('keptPattern').displaySize).toEqual([4, 4]);
+        expect(patternAtlas.getPixelSize()).toEqual(sizeInAtlas(4));
+    });
+
+    test('uploads the atlas to its texture only once it changed', () => {
+        const update = vi.spyOn(Texture.prototype, 'update');
+        const bind = vi.spyOn(Texture.prototype, 'bind');
+        imageManager.addImage('pattern', createStyleImage(4));
+        patternAtlas.getPattern('pattern');
+
+        patternAtlas.bind(context);
+        const uploadsToCreateTheTexture = update.mock.calls.length;
+        patternAtlas.bind(context);
+        expect(update).toHaveBeenCalledTimes(uploadsToCreateTheTexture);
+
+        imageManager.addImage('anotherPattern', createStyleImage(4));
+        patternAtlas.getPattern('anotherPattern');
+        patternAtlas.bind(context);
+        patternAtlas.bind(context);
+
+        expect(update).toHaveBeenCalledTimes(uploadsToCreateTheTexture + 1);
+        expect(bind).toHaveBeenCalledTimes(4);
+    });
+
+    test('destroy releases the texture and empties the atlas', () => {
+        const destroy = vi.spyOn(Texture.prototype, 'destroy');
+        imageManager.addImage('pattern', createStyleImage(4));
+        patternAtlas.getPattern('pattern');
+        patternAtlas.bind(context);
+
+        patternAtlas.destroy();
+
+        expect(destroy).toHaveBeenCalledTimes(1);
+        expect(patternAtlas.getPixelSize()).toEqual({width: 1, height: 1});
+    });
+
+    test('destroy does nothing to an atlas that was never bound', () => {
+        const destroy = vi.spyOn(Texture.prototype, 'destroy');
+
+        expect(() => patternAtlas.destroy()).not.toThrow();
+        expect(destroy).not.toHaveBeenCalled();
+    });
+});