maplibre-gl-layers 0.1.0 → 0.3.0

package/dist/index.cjs

@@ -1,12 +1,12 @@
 "use strict";
 /*!
  * name: maplibre-gl-layers
- * version: 0.1.0
+ * version: 0.3.0
  * description: MapLibre's layer extension library enabling the display, movement, and modification of large numbers of dynamic sprite images
  * author: Kouji Matsui (@kekyo@mi.kekyo.net)
  * license: MIT
  * repository.url: https://github.com/kekyo/maplibre-gl-layers.git
- * git.commit.hash: 88b09a93779279947d9c6b1e3a7538d4d197dbcb
+ * git.commit.hash: fd90d1fd66e4ca9c0defa49e68ecaeb9c14fbd06
  */
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 var maplibreGl$1 = { exports: {} };
@@ -21505,6 +21505,27 @@ const screenToClip = (x, y, drawingBufferWidth, drawingBufferHeight, pixelRatio)
   const clipY = 1 - deviceY / drawingBufferHeight * 2;
   return [clipX, clipY];
 };
+const clipToScreen = (clipPosition, drawingBufferWidth, drawingBufferHeight, pixelRatio) => {
+  const [clipX, clipY, , clipW] = clipPosition;
+  if (!Number.isFinite(clipW) || clipW === 0) {
+    return null;
+  }
+  const invW = 1 / clipW;
+  const ndcX = clipX * invW;
+  const ndcY = clipY * invW;
+  const deviceX = (ndcX + 1) * 0.5 * drawingBufferWidth;
+  const deviceY = (1 - ndcY) * 0.5 * drawingBufferHeight;
+  if (!Number.isFinite(deviceX) || !Number.isFinite(deviceY)) {
+    return null;
+  }
+  if (!Number.isFinite(pixelRatio) || pixelRatio === 0) {
+    return null;
+  }
+  return {
+    x: deviceX / pixelRatio,
+    y: deviceY / pixelRatio
+  };
+};
 const TRIANGLE_INDICES = [0, 1, 2, 2, 1, 3];
 const UV_CORNERS = [
   [0, 0],
@@ -21664,6 +21685,7 @@ const calculateBillboardCornerScreenPositions = (params) => {
   return corners;
 };
 const calculateSurfaceCenterPosition = (params) => {
+  var _a, _b;
   const {
     baseLngLat,
     imageWidth,
@@ -21674,8 +21696,38 @@ const calculateSurfaceCenterPosition = (params) => {
     totalRotateDeg,
     anchor,
     offset,
-    project
+    project,
+    projectToClipSpace,
+    drawingBufferWidth,
+    drawingBufferHeight,
+    pixelRatio,
+    altitudeMeters,
+    resolveAnchorless = false
   } = params;
+  const baseAltitude = Number.isFinite(altitudeMeters) ? altitudeMeters : (_a = baseLngLat.z) != null ? _a : 0;
+  const hasClipProjection = typeof drawingBufferWidth === "number" && drawingBufferWidth > 0 && typeof drawingBufferHeight === "number" && drawingBufferHeight > 0 && typeof pixelRatio === "number" && Number.isFinite(pixelRatio) && pixelRatio !== 0 && typeof projectToClipSpace === "function";
+  const projectPoint = (lngLat) => {
+    var _a2;
+    if (hasClipProjection && projectToClipSpace) {
+      const clip = projectToClipSpace(
+        lngLat.lng,
+        lngLat.lat,
+        (_a2 = lngLat.z) != null ? _a2 : baseAltitude
+      );
+      if (clip) {
+        const screen = clipToScreen(
+          clip,
+          drawingBufferWidth,
+          drawingBufferHeight,
+          pixelRatio
+        );
+        if (screen) {
+          return screen;
+        }
+      }
+    }
+    return project ? project(lngLat) : null;
+  };
   const worldDims = calculateSurfaceWorldDimensions(
     imageWidth,
     imageHeight,
@@ -21700,12 +21752,31 @@ const calculateSurfaceCenterPosition = (params) => {
     totalEast,
     totalNorth
   );
-  const center = project(displaced);
+  const center = projectPoint(displaced);
+  let anchorlessCenter;
+  let anchorlessDisplacement;
+  let anchorlessLngLat;
+  if (resolveAnchorless) {
+    anchorlessDisplacement = {
+      east: offsetMeters.east,
+      north: offsetMeters.north
+    };
+    anchorlessLngLat = applySurfaceDisplacement(
+      baseLngLat.lng,
+      baseLngLat.lat,
+      anchorlessDisplacement.east,
+      anchorlessDisplacement.north
+    );
+    anchorlessCenter = (_b = projectPoint(anchorlessLngLat)) != null ? _b : null;
+  }
   return {
     center,
     worldDimensions: worldDims,
     totalDisplacement: { east: totalEast, north: totalNorth },
-    displacedLngLat: displaced
+    displacedLngLat: displaced,
+    anchorlessCenter,
+    anchorlessDisplacement,
+    anchorlessLngLat
   };
 };
 const SURFACE_BASE_CORNERS = [
@@ -22324,6 +22395,16 @@ const createSpriteLayer = (options) => {
   let uniformTextureLocation = null;
   let uniformOpacityLocation = null;
   const images = /* @__PURE__ */ new Map();
+  const queuedTextureIds = /* @__PURE__ */ new Set();
+  const queueTextureUpload = (image) => {
+    queuedTextureIds.add(image.id);
+  };
+  const cancelQueuedTextureUpload = (imageId) => {
+    queuedTextureIds.delete(imageId);
+  };
+  const clearTextureQueue = () => {
+    queuedTextureIds.clear();
+  };
   const sprites = /* @__PURE__ */ new Map();
   const getImageState = (sprite, subLayer, order) => {
     var _a2;
@@ -22410,7 +22491,12 @@ const createSpriteLayer = (options) => {
       spriteMaxPixel,
       effectivePixelsPerMeter,
       images: images2,
-      mapInstance
+      mapInstance,
+      drawingBufferWidth,
+      drawingBufferHeight,
+      pixelRatio,
+      clipContext,
+      altitudeMeters
     } = params;
     const useResolvedAnchor = (_a2 = options2 == null ? void 0 : options2.useResolvedAnchor) != null ? _a2 : false;
     let spriteCache = originCenterCache.get(sprite.spriteId);
@@ -22479,6 +22565,7 @@ const createSpriteLayer = (options) => {
       // Otherwise use the sprite's own interpolated geographic location.
       { lng: sprite.currentLocation.lng, lat: sprite.currentLocation.lat }
     );
+    const projectToClipSpace = clipContext ? (lng, lat, elevation) => projectLngLatToClipSpace(lng, lat, elevation, clipContext) : void 0;
     const surfacePlacement = calculateSurfaceCenterPosition({
       baseLngLat,
       imageWidth: imageResourceRef == null ? void 0 : imageResourceRef.width,
@@ -22489,33 +22576,21 @@ const createSpriteLayer = (options) => {
       totalRotateDeg: totalRotDeg,
       anchor: img.anchor,
       offset: img.offset,
-      project: (lngLat) => {
+      projectToClipSpace,
+      drawingBufferWidth,
+      drawingBufferHeight,
+      pixelRatio,
+      altitudeMeters,
+      resolveAnchorless: true,
+      project: projectToClipSpace === void 0 ? (lngLat) => {
         const projectedPoint = mapInstance.project(lngLat);
         if (!projectedPoint) {
           return null;
         }
         return { x: projectedPoint.x, y: projectedPoint.y };
-      }
+      } : void 0
     });
-    const anchorlessPlacement = calculateSurfaceCenterPosition({
-      baseLngLat,
-      imageWidth: imageResourceRef == null ? void 0 : imageResourceRef.width,
-      imageHeight: imageResourceRef == null ? void 0 : imageResourceRef.height,
-      baseMetersPerPixel,
-      imageScale: imageScaleLocal,
-      zoomScaleFactor,
-      totalRotateDeg: totalRotDeg,
-      anchor: void 0,
-      offset: img.offset,
-      project: (lngLat) => {
-        const projectedPoint = mapInstance.project(lngLat);
-        if (!projectedPoint) {
-          return null;
-        }
-        return { x: projectedPoint.x, y: projectedPoint.y };
-      }
-    });
-    const anchorlessCenter = (_g = anchorlessPlacement.center) != null ? _g : {
+    const anchorlessCenter = (_g = surfacePlacement.anchorlessCenter) != null ? _g : {
       // If the anchorless placement could not be projected, fall back to the original screen position.
       x: baseX,
       y: baseY
@@ -22529,13 +22604,19 @@ const createSpriteLayer = (options) => {
   };
   const renderTargetEntries = [];
   const hitTestEntries = [];
+  const ensureHitTestCorners = (imageEntry) => {
+    if (!imageEntry.hitTestCorners) {
+      imageEntry.hitTestCorners = [
+        { x: 0, y: 0 },
+        { x: 0, y: 0 },
+        { x: 0, y: 0 },
+        { x: 0, y: 0 }
+      ];
+    }
+    return imageEntry.hitTestCorners;
+  };
   const registerHitTestEntry = (spriteEntry, imageEntry, screenCorners) => {
-    const corners = [
-      { x: screenCorners[0].x, y: screenCorners[0].y },
-      { x: screenCorners[1].x, y: screenCorners[1].y },
-      { x: screenCorners[2].x, y: screenCorners[2].y },
-      { x: screenCorners[3].x, y: screenCorners[3].y }
-    ];
+    const corners = screenCorners;
     let minX = corners[0].x;
     let maxX = corners[0].x;
     let minY = corners[0].y;
@@ -22663,13 +22744,19 @@ const createSpriteLayer = (options) => {
     if (!gl) {
       return;
     }
+    if (queuedTextureIds.size === 0) {
+      return;
+    }
     const glContext = gl;
-    images.forEach((image) => {
-      if (!image.dirty || !image.bitmap) {
+    queuedTextureIds.forEach((imageId) => {
+      const image = images.get(imageId);
+      queuedTextureIds.delete(imageId);
+      if (!image || !image.bitmap) {
         return;
       }
       if (image.texture) {
         glContext.deleteTexture(image.texture);
+        image.texture = void 0;
       }
       const texture = glContext.createTexture();
       if (!texture) {
@@ -22706,7 +22793,6 @@ const createSpriteLayer = (options) => {
         image.bitmap
       );
       image.texture = texture;
-      image.dirty = false;
     });
   };
   const scheduleRender = () => {
@@ -22733,6 +22819,17 @@ const createSpriteLayer = (options) => {
         });
       });
     });
+    renderTargetEntries.sort((a, b) => {
+      const aImage = a[1];
+      const bImage = b[1];
+      if (aImage.subLayer !== bImage.subLayer) {
+        return aImage.subLayer - bImage.subLayer;
+      }
+      if (aImage.order !== bImage.order) {
+        return aImage.order - bImage.order;
+      }
+      return aImage.imageId.localeCompare(bImage.imageId);
+    });
   };
   const onAdd = (mapInstance, glContext) => {
     map = mapInstance;
@@ -22852,7 +22949,7 @@ const createSpriteLayer = (options) => {
           glContext.deleteTexture(image.texture);
         }
         image.texture = void 0;
-        image.dirty = true;
+        queueTextureUpload(image);
       });
       if (vertexBuffer) {
         glContext.deleteBuffer(vertexBuffer);
@@ -22998,7 +23095,7 @@ const createSpriteLayer = (options) => {
     );
     glContext.uniform1i(uniformTextureLocation, 0);
     const drawSpriteImage = (spriteEntry, imageEntry, imageResource, originCenterCache2) => {
-      var _a2, _b, _c, _d, _e, _f, _g, _h, _i;
+      var _a2, _b, _c, _d, _e, _f, _g, _h, _i, _j;
       let screenCornerBuffer = null;
       const anchor = (_a2 = imageEntry.anchor) != null ? _a2 : DEFAULT_ANCHOR;
       const offsetDef = (_b = imageEntry.offset) != null ? _b : DEFAULT_IMAGE_OFFSET;
@@ -23037,18 +23134,23 @@ const createSpriteLayer = (options) => {
         baseMetersPerPixel,
         spriteMinPixel,
         spriteMaxPixel,
-        effectivePixelsPerMeter
+        effectivePixelsPerMeter,
+        drawingBufferWidth,
+        drawingBufferHeight,
+        pixelRatio,
+        clipContext,
+        altitudeMeters: (_f = spriteEntry.currentLocation.z) != null ? _f : 0
       };
       let baseProjected = { x: projected.x, y: projected.y };
       if (imageEntry.originLocation !== void 0) {
-        const refImg = (_f = spriteEntry.images.get(imageEntry.originLocation.subLayer)) == null ? void 0 : _f.get(imageEntry.originLocation.order);
+        const refImg = (_g = spriteEntry.images.get(imageEntry.originLocation.subLayer)) == null ? void 0 : _g.get(imageEntry.originLocation.order);
         if (refImg) {
           baseProjected = computeImageCenterXY(
             spriteEntry,
             refImg,
             centerParams,
             {
-              useResolvedAnchor: (_g = imageEntry.originLocation.useResolvedAnchor) != null ? _g : false
+              useResolvedAnchor: (_h = imageEntry.originLocation.useResolvedAnchor) != null ? _h : false
             }
           );
         }
@@ -23074,10 +23176,15 @@ const createSpriteLayer = (options) => {
           totalRotateDeg,
           anchor,
           offset: offsetDef,
-          project: (lngLat) => {
+          projectToClipSpace: (lng, lat, elevation) => projectLngLatToClipSpace(lng, lat, elevation, clipContext),
+          drawingBufferWidth,
+          drawingBufferHeight,
+          pixelRatio,
+          altitudeMeters: (_i = spriteEntry.currentLocation.z) != null ? _i : 0,
+          project: !clipContext ? (lngLat) => {
             const result = mapInstance.project(lngLat);
             return result ? { x: result.x, y: result.y } : null;
-          }
+          } : void 0
         });
         if (!surfaceCenter.center) {
           return;
@@ -23093,7 +23200,7 @@ const createSpriteLayer = (options) => {
           totalRotateDeg,
           offsetMeters
         });
-        const screenCornersLocal = new Array(4);
+        const hitTestCorners = ensureHitTestCorners(imageEntry);
         let bufferOffset = 0;
         for (const index of TRIANGLE_INDICES) {
           const displacement = cornerDisplacements[index];
@@ -23107,25 +23214,24 @@ const createSpriteLayer = (options) => {
             displaced.lng,
             displaced.lat,
             // Default altitude to zero when sprites lack explicit elevation.
-            (_h = spriteEntry.currentLocation.z) != null ? _h : 0,
+            (_j = spriteEntry.currentLocation.z) != null ? _j : 0,
             clipContext
           );
           if (!clipPosition) {
             return;
           }
-          const projectedCorner = mapInstance.project({
-            lng: displaced.lng,
-            lat: displaced.lat,
-            // Mirror the same altitude assumption when projecting back to screen space.
-            z: (_i = spriteEntry.currentLocation.z) != null ? _i : 0
-          });
-          if (!projectedCorner) {
+          const screenCorner = clipToScreen(
+            clipPosition,
+            drawingBufferWidth,
+            drawingBufferHeight,
+            pixelRatio
+          );
+          if (!screenCorner) {
             return;
           }
-          screenCornersLocal[index] = {
-            x: projectedCorner.x,
-            y: projectedCorner.y
-          };
+          const targetCorner = hitTestCorners[index];
+          targetCorner.x = screenCorner.x;
+          targetCorner.y = screenCorner.y;
           let [clipX, clipY, clipZ, clipW] = clipPosition;
           {
             const orderIndex = Math.min(imageEntry.order, ORDER_MAX - 1);
@@ -23145,7 +23251,7 @@ const createSpriteLayer = (options) => {
           QUAD_VERTEX_SCRATCH[bufferOffset++] = u;
           QUAD_VERTEX_SCRATCH[bufferOffset++] = v;
         }
-        screenCornerBuffer = screenCornersLocal;
+        screenCornerBuffer = hitTestCorners;
       } else {
         const placement = calculateBillboardCenterPosition({
           base: baseProjected,
@@ -23169,6 +23275,7 @@ const createSpriteLayer = (options) => {
           anchor,
           totalRotateDeg
         });
+        const hitTestCorners = ensureHitTestCorners(imageEntry);
         let bufferOffset = 0;
         for (const index of TRIANGLE_INDICES) {
           const corner = corners[index];
@@ -23186,13 +23293,13 @@ const createSpriteLayer = (options) => {
           QUAD_VERTEX_SCRATCH[bufferOffset++] = corner.u;
           QUAD_VERTEX_SCRATCH[bufferOffset++] = corner.v;
         }
-        screenCornerBuffer = [
-          // Preserve the resolved screen-space corners for hit testing below.
-          { x: corners[0].x, y: corners[0].y },
-          { x: corners[1].x, y: corners[1].y },
-          { x: corners[2].x, y: corners[2].y },
-          { x: corners[3].x, y: corners[3].y }
-        ];
+        for (let i = 0; i < corners.length; i++) {
+          const source = corners[i];
+          const target = hitTestCorners[i];
+          target.x = source.x;
+          target.y = source.y;
+        }
+        screenCornerBuffer = hitTestCorners;
       }
       if (screenCornerBuffer && screenCornerBuffer.length === 4) {
         registerHitTestEntry(
@@ -23210,7 +23317,7 @@ const createSpriteLayer = (options) => {
     const originCenterCache = /* @__PURE__ */ new Map();
     const sortedSubLayerBuckets = buildSortedSubLayerBuckets(renderTargetEntries);
     const renderSortedBucket = (bucket) => {
-      var _a2, _b, _c, _d, _e;
+      var _a2, _b, _c, _d, _e, _f;
       const itemsWithDepth = [];
       const projectToClipSpace = (lng, lat, elevation) => projectLngLatToClipSpace(lng, lat, elevation, clipContext);
       const unprojectPoint = ({ x, y }) => {
@@ -23256,10 +23363,15 @@ const createSpriteLayer = (options) => {
           baseMetersPerPixel,
           spriteMinPixel,
           spriteMaxPixel,
-          effectivePixelsPerMeter
+          effectivePixelsPerMeter,
+          drawingBufferWidth,
+          drawingBufferHeight,
+          pixelRatio,
+          clipContext,
+          altitudeMeters: (_a2 = spriteEntry.currentLocation.z) != null ? _a2 : 0
         };
-        const anchorResolved = (_a2 = imageEntry.anchor) != null ? _a2 : DEFAULT_ANCHOR;
-        const offsetResolved = (_b = imageEntry.offset) != null ? _b : DEFAULT_IMAGE_OFFSET;
+        const anchorResolved = (_b = imageEntry.anchor) != null ? _b : DEFAULT_ANCHOR;
+        const offsetResolved = (_c = imageEntry.offset) != null ? _c : DEFAULT_IMAGE_OFFSET;
         const depthCenter = computeImageCenterXY(
           spriteEntry,
           imageEntry,
@@ -23268,7 +23380,7 @@ const createSpriteLayer = (options) => {
         );
         let depthKey;
         if (imageEntry.mode === "surface") {
-          const imageScale = (_c = imageEntry.scale) != null ? _c : 1;
+          const imageScale = (_d = imageEntry.scale) != null ? _d : 1;
           const worldDims = calculateSurfaceWorldDimensions(
             imageResource.width,
             imageResource.height,
@@ -23277,7 +23389,7 @@ const createSpriteLayer = (options) => {
             zoomScaleFactor
           );
           const totalRotateDeg = Number.isFinite(imageEntry.displayedRotateDeg) ? imageEntry.displayedRotateDeg : normaliseAngleDeg(
-            ((_d = imageEntry.resolvedBaseRotateDeg) != null ? _d : 0) + ((_e = imageEntry.rotateDeg) != null ? _e : 0)
+            ((_e = imageEntry.resolvedBaseRotateDeg) != null ? _e : 0) + ((_f = imageEntry.rotateDeg) != null ? _f : 0)
           );
           const offsetMeters = calculateSurfaceOffsetMeters(
             offsetResolved,
@@ -23399,14 +23511,15 @@ const createSpriteLayer = (options) => {
     if (images.has(imageId)) {
       return false;
     }
-    images.set(imageId, {
+    const image = {
       id: imageId,
       width: bitmap.width,
       height: bitmap.height,
       bitmap,
-      texture: void 0,
-      dirty: true
-    });
+      texture: void 0
+    };
+    images.set(imageId, image);
+    queueTextureUpload(image);
     ensureTextures();
     scheduleRender();
     return true;
@@ -23592,14 +23705,15 @@ const createSpriteLayer = (options) => {
       totalHeight,
       renderPixelRatio
     );
-    images.set(textGlyphId, {
+    const image = {
       id: textGlyphId,
       width: totalWidth,
       height: totalHeight,
       bitmap,
-      texture: void 0,
-      dirty: true
-    });
+      texture: void 0
+    };
+    images.set(textGlyphId, image);
+    queueTextureUpload(image);
     ensureTextures();
     scheduleRender();
     return true;
@@ -23613,12 +23727,30 @@ const createSpriteLayer = (options) => {
     if (glContext && image.texture) {
       glContext.deleteTexture(image.texture);
     }
+    cancelQueuedTextureUpload(imageId);
     images.delete(imageId);
     ensureRenderTargetEntries();
     scheduleRender();
     return true;
   };
-  const addSprite = (spriteId, init) => {
+  const unregisterAllImages = () => {
+    const glContext = gl;
+    images.forEach((image) => {
+      var _a2, _b;
+      if (glContext && image.texture) {
+        glContext.deleteTexture(image.texture);
+      }
+      if (image.bitmap) {
+        (_b = (_a2 = image.bitmap).close) == null ? void 0 : _b.call(_a2);
+      }
+    });
+    images.clear();
+    clearTextureQueue();
+    ensureRenderTargetEntries();
+    scheduleRender();
+  };
+  const getAllImageIds = () => Array.from(images.keys());
+  const addSpriteInternal = (spriteId, init) => {
     var _a2, _b, _c, _d;
     if (sprites.get(spriteId)) {
       return false;
@@ -23697,18 +23829,90 @@ const createSpriteLayer = (options) => {
       lastAutoRotationAngleDeg: 0
     };
     sprites.set(spriteId, spriteState);
-    ensureRenderTargetEntries();
-    scheduleRender();
     return true;
   };
+  const resolveSpriteInitCollection = (collection) => {
+    if (Array.isArray(collection)) {
+      return collection.map((entry) => [
+        entry.spriteId,
+        entry
+      ]);
+    }
+    return Object.entries(collection);
+  };
+  const addSprite = (spriteId, init) => {
+    const isAdded = addSpriteInternal(spriteId, init);
+    if (isAdded) {
+      ensureRenderTargetEntries();
+      scheduleRender();
+    }
+    return isAdded;
+  };
+  const addSprites = (collection) => {
+    let addedCount = 0;
+    for (const [spriteId, spriteInit] of resolveSpriteInitCollection(
+      collection
+    )) {
+      if (addSpriteInternal(spriteId, spriteInit)) {
+        addedCount++;
+      }
+    }
+    if (addedCount > 0) {
+      ensureRenderTargetEntries();
+      scheduleRender();
+    }
+    return addedCount;
+  };
+  const removeSpriteInternal = (spriteId) => sprites.delete(spriteId);
   const removeSprite = (spriteId) => {
-    if (!sprites.delete(spriteId)) {
+    const removed = removeSpriteInternal(spriteId);
+    if (!removed) {
       return false;
     }
     ensureRenderTargetEntries();
     scheduleRender();
     return true;
   };
+  const removeSprites = (spriteIds) => {
+    let removedCount = 0;
+    for (const spriteId of spriteIds) {
+      if (removeSpriteInternal(spriteId)) {
+        removedCount++;
+      }
+    }
+    if (removedCount > 0) {
+      ensureRenderTargetEntries();
+      scheduleRender();
+    }
+    return removedCount;
+  };
+  const removeAllSprites = () => {
+    const removedCount = sprites.size;
+    if (removedCount === 0) {
+      return 0;
+    }
+    sprites.clear();
+    ensureRenderTargetEntries();
+    scheduleRender();
+    return removedCount;
+  };
+  const removeAllSpriteImages = (spriteId) => {
+    const sprite = sprites.get(spriteId);
+    if (!sprite) {
+      return 0;
+    }
+    if (sprite.images.size === 0) {
+      return 0;
+    }
+    let removedCount = 0;
+    sprite.images.forEach((orderMap) => {
+      removedCount += orderMap.size;
+    });
+    sprite.images.clear();
+    ensureRenderTargetEntries();
+    scheduleRender();
+    return removedCount;
+  };
   const getSpriteState = (spriteId) => {
     return sprites.get(spriteId);
   };
@@ -24061,6 +24265,124 @@ const createSpriteLayer = (options) => {
     }
     return updatedCount;
   };
+  const mutateSprites = (sourceItems, mutator) => {
+    if (sourceItems.length === 0) {
+      return 0;
+    }
+    let changedCount = 0;
+    let isRequiredRender = false;
+    let currentSprite = void 0;
+    let didMutateImages = false;
+    const operationResult = {
+      isUpdated: false
+    };
+    const updateObject = {
+      getImageIndexMap: () => {
+        const map2 = /* @__PURE__ */ new Map();
+        currentSprite.images.forEach((inner, subLayer) => {
+          map2.set(subLayer, new Set(inner.keys()));
+        });
+        return map2;
+      },
+      addImage: (subLayer, order, imageInit) => {
+        const added = addSpriteImageInternal(
+          currentSprite,
+          subLayer,
+          order,
+          imageInit,
+          operationResult
+        );
+        if (added) {
+          didMutateImages = true;
+        }
+        return added;
+      },
+      updateImage: (subLayer, order, imageUpdate) => {
+        const updated = updateSpriteImageInternal(
+          currentSprite,
+          subLayer,
+          order,
+          imageUpdate,
+          operationResult
+        );
+        if (updated) {
+          didMutateImages = true;
+        }
+        return updated;
+      },
+      removeImage: (subLayer, order) => {
+        const removed = removeSpriteImageInternal(
+          currentSprite,
+          subLayer,
+          order,
+          operationResult
+        );
+        if (removed) {
+          didMutateImages = true;
+        }
+        return removed;
+      }
+    };
+    for (const sourceItem of sourceItems) {
+      const spriteId = sourceItem.spriteId;
+      const sprite = sprites.get(spriteId);
+      if (!sprite) {
+        const init = mutator.add(sourceItem);
+        if (!init) {
+          continue;
+        }
+        if (addSpriteInternal(spriteId, init)) {
+          changedCount++;
+          isRequiredRender = true;
+        }
+        continue;
+      }
+      currentSprite = sprite;
+      operationResult.isUpdated = false;
+      didMutateImages = false;
+      const decision = mutator.modify(
+        sourceItem,
+        sprite,
+        updateObject
+      );
+      if (decision === "remove") {
+        if (removeSpriteInternal(spriteId)) {
+          changedCount++;
+          isRequiredRender = true;
+        }
+      } else {
+        const updateResult = updateSpriteInternal(spriteId, updateObject);
+        let spriteChanged = false;
+        switch (updateResult) {
+          case "updated":
+            spriteChanged = true;
+            break;
+          case "isRequiredRender":
+            spriteChanged = true;
+            isRequiredRender = true;
+            break;
+        }
+        if (didMutateImages) {
+          spriteChanged = true;
+          isRequiredRender = true;
+        }
+        if (spriteChanged) {
+          changedCount++;
+        }
+      }
+      updateObject.isEnabled = void 0;
+      updateObject.location = void 0;
+      updateObject.interpolation = void 0;
+      updateObject.tag = void 0;
+      operationResult.isUpdated = false;
+      didMutateImages = false;
+    }
+    if (isRequiredRender) {
+      ensureRenderTargetEntries();
+      scheduleRender();
+    }
+    return changedCount;
+  };
   const updateForEach = (updater) => {
     let updatedCount = 0;
     let isRequiredRender = false;
@@ -24135,14 +24457,21 @@ const createSpriteLayer = (options) => {
     registerImage,
     registerTextGlyph,
     unregisterImage,
+    unregisterAllImages,
+    getAllImageIds,
     addSprite,
+    addSprites,
     removeSprite,
+    removeSprites,
+    removeAllSprites,
+    removeAllSpriteImages,
     getSpriteState,
     addSpriteImage,
     updateSpriteImage,
     removeSpriteImage,
     updateSprite,
     updateBulk,
+    mutateSprites,
     updateForEach,
     on: addEventListener2,
     off: removeEventListener2