@lijuhong1981/three.instancedsprite 1.1.0 → 2.0.0

package/src/InstancedSpriteCollection.js

@@ -2,10 +2,10 @@ import Check from "@lijuhong1981/jscheck/src/Check.js";
 import {
     MathUtils,
     Object3D,
-    Texture
 } from "three";
 import InstancedSprite from "./InstancedSprite.js";
 import InstancedSpriteMesh from "./InstancedSpriteMesh.js";
+import TextureAtlas from "./TextureAtlas.js";
 
 /**
  * @import InstancedSpriteOptions from "./InstancedSprite.js";
@@ -19,18 +19,22 @@ const imageCache = new Map();
 
 /**
  * InstancedSpriteCollection类，批量管理InstancedSprite实例
- * 
+ *
  * * 继承自Object3D
- * * 根据InstancedSprite的图像属性生成InstancedSpriteMaterial和InstancedSpriteMesh，
- * * 管理InstancedSprite与InstancedSpriteMesh实例
+ * * 使用纹理图集将不同图片打包，一张图集对应一个 InstancedSpriteMesh（一次 draw call）
+ * * 图集扩容到上限后会新建图集与 Mesh
  * @extends Object3D
  */
 class InstancedSpriteCollection extends Object3D {
     /**
-     * @param {boolean} [useNodeMaterial=false] - 是否使用TSL的NodeMaterial，默认false
+     * @param {object} [options] - 配置项
+     * @param {boolean} [options.useNodeMaterial=false] - 是否使用TSL的NodeMaterial（WebGPU），默认false
+     * @param {number} [options.initialSize=1024] - 图集初始边长
+     * @param {number} [options.maxSize=8192] - 图集最大边长
+     * @param {number} [options.padding=2] - 子图间距
      * @constructor
     */
-    constructor(useNodeMaterial = false) {
+    constructor(options = {}) {
         super();
         /**
          * 是否使用TSL的NodeMaterial，默认false
@@ -38,25 +42,49 @@ class InstancedSpriteCollection extends Object3D {
          * @readonly
          * @default false
         */
-        this.useNodeMaterial = useNodeMaterial;
+        this.useNodeMaterial = options.useNodeMaterial === true;
         /**
          * 对象类型标识
          * @type {string}
          * @readonly
         */
         this.type = "InstancedSpriteCollection";
-        // this.frustumCulled = false;
         /**
          * @type {Array<InstancedSprite>}
          * @ignore
         */
         this._instancedSprites = [];
         /**
-         * @type {Map<HTMLImageElement|HTMLCanvasElement, InstancedSpriteMesh>}
+         * @type {Map<string, InstancedSprite>}
          * @ignore
         */
-        this._meshes = new Map();
+        this._spriteByUuid = new Map();
+        /**
+         * 图集与对应 Mesh 的列表，按创建顺序排列
+         * @type {Array<{atlas:TextureAtlas, mesh:InstancedSpriteMesh}>}
+         * @ignore
+        */
+        this._atlasList = [];
+        /**
+         * 图片源到所在图集条目的索引，避免同一张图片被重复打包进不同图集
+         * @type {Map<HTMLImageElement|HTMLCanvasElement, {atlas:TextureAtlas, mesh:InstancedSpriteMesh}>}
+         * @ignore
+        */
+        this._imageEntry = new Map();
+        /**
+         * 图集配置项，新建图集时使用
+         * @type {object}
+         * @ignore
+        */
+        this._atlasOptions = options;
         this._depthTest = true;
+        this._depthWrite = true;
+        /**
+         * 预留容量，在创建新Mesh时应用，undefined表示不预留
+         * @type {number|undefined}
+         * @ignore
+        */
+        this._reservedCapacity = undefined;
     }
     /**
      * InstancedSpriteCollection对象标识
@@ -71,11 +99,23 @@ class InstancedSpriteCollection extends Object3D {
     */
     get depthTest() { return this._depthTest; }
     set depthTest(value) {
-        Check.typeOf.boolean(value, 'depthTest');
+        Check.typeOf.boolean('depthTest', value);
         this._depthTest = value;
-        const meshes = this._meshes.values();
-        for (const mesh of meshes) {
-            mesh.depthTest = value;
+        for (const entry of this._atlasList) {
+            entry.mesh.depthTest = value;
+        }
+    }
+    /**
+     * 深度写入开关，默认为true；多个半透明 Sprite 重叠时，开启深度写入可能导致排序瑕疵（后方 Sprite 被错误遮挡），关闭可缓解，适合半透明标签/粒子等场景
+     * @type {boolean}
+     * @default true
+    */
+    get depthWrite() { return this._depthWrite; }
+    set depthWrite(value) {
+        Check.typeOf.boolean('depthWrite', value);
+        this._depthWrite = value;
+        for (const entry of this._atlasList) {
+            entry.mesh.depthWrite = value;
         }
     }
     /**
@@ -88,35 +128,7 @@ class InstancedSpriteCollection extends Object3D {
                 source.src = MathUtils.generateUUID();
             if (!imageCache.has(source.src))
                 imageCache.set(source.src, source);
-            let mesh = this._meshes.get(source);
-            if (!mesh) {
-                const texture = new Texture();
-                if (source instanceof HTMLCanvasElement || (source instanceof HTMLImageElement && source.complete)) {
-                    texture.image = source;
-                    texture.needsUpdate = true;
-                } else {
-                    const onload = () => {
-                        source.removeEventListener('load', onload);
-                        texture.image = source;
-                        texture.needsUpdate = true;
-                        sprite.imageSize.set(source.width, source.height);
-                    };
-                    source.addEventListener('load', onload);
-                }
-                mesh = new InstancedSpriteMesh(this, texture);
-                mesh.depthTest = this._depthTest;
-                this._meshes.set(source, mesh);
-                super.add(mesh);
-            }
-            if (sprite._mesh === mesh)
-                return;
-            // instancedSprite如果已经有所属的mesh了，则从所属的Mesh中移除
-            sprite.remove();
-            mesh.add(sprite);
-            sprite._image = source;
-            if (source.width !== 0 && source.height !== 0) {
-                sprite.imageSize.set(source.width, source.height);
-            }
+            this._setImageAtlas(source, sprite);
         } else if (typeof source === 'string') {
             let image = imageCache.get(source);
             if (!image) {
@@ -129,6 +141,95 @@ class InstancedSpriteCollection extends Object3D {
             throw new Error('Invalid image source type ' + source);
         }
     }
+    /**
+     * 将图片打包进图集并加入对应 Mesh
+     * @param {HTMLImageElement|HTMLCanvasElement} source
+     * @param {InstancedSprite} sprite
+     * @private
+    */
+    _setImageAtlas(source, sprite) {
+        sprite._image = source;
+        const loaded = source instanceof HTMLCanvasElement || (source.width > 0 && source.height > 0);
+        if (loaded) {
+            this._assignAtlas(source, sprite);
+        } else {
+            const onload = () => {
+                source.removeEventListener('load', onload);
+                // 图片加载完成前 sprite 可能已被移除，此时不再加入图集
+                if (this._spriteByUuid.get(sprite.uuid) === sprite)
+                    this._assignAtlas(source, sprite);
+            };
+            source.addEventListener('load', onload);
+        }
+    }
+    /**
+     * 将已加载的图片打包进图集，设置 sprite 的 uvRect 与 imageSize，并加入图集 Mesh
+     * @param {HTMLImageElement|HTMLCanvasElement} source
+     * @param {InstancedSprite} sprite
+     * @private
+    */
+    _assignAtlas(source, sprite) {
+        // 已打包过的图片复用其所在图集，避免把同一张图重复打进不同图集
+        let entry = this._imageEntry.get(source);
+        if (!entry) {
+            entry = this._atlasList[this._atlasList.length - 1];
+            let rect = entry ? entry.atlas.add(source) : null;
+            if (rect === null && entry) {
+                // 图集已满，尝试扩容
+                if (entry.atlas.grow()) {
+                    // 扩容会重建纹理，需同步更新 Mesh 材质引用的纹理
+                    entry.mesh.material.texture = entry.atlas.texture;
+                    this._recomputeUvRects(entry);
+                    rect = entry.atlas.add(source);
+                }
+            }
+            if (rect === null) {
+                // 图集已达最大尺寸，新建图集与 Mesh
+                entry = this._createAtlasEntry();
+                this._atlasList.push(entry);
+                rect = entry.atlas.add(source);
+            }
+            this._imageEntry.set(source, entry);
+        }
+        const rect = entry.atlas.getRect(source);
+        const uv = entry.atlas.getUvRect(rect);
+        sprite.uvRect.set(uv[0], uv[1], uv[2], uv[3]);
+        sprite.imageSize.set(source.width, source.height);
+        sprite._remove();
+        entry.mesh.add(sprite);
+    }
+    /**
+     * 图集扩容后重新归一化该图集内所有 sprite 的 uvRect
+     * @param {{atlas:TextureAtlas, mesh:InstancedSpriteMesh}} entry
+     * @private
+    */
+    _recomputeUvRects(entry) {
+        for (const sprite of this._instancedSprites) {
+            if (sprite._mesh === entry.mesh) {
+                const rect = entry.atlas.getRect(sprite._image);
+                if (rect) {
+                    const uv = entry.atlas.getUvRect(rect);
+                    sprite.uvRect.set(uv[0], uv[1], uv[2], uv[3]);
+                }
+            }
+        }
+    }
+    /**
+     * 创建新的图集与对应 Mesh
+     * @returns {{atlas:TextureAtlas, mesh:InstancedSpriteMesh}}
+     * @private
+    */
+    _createAtlasEntry() {
+        const atlas = new TextureAtlas(this._atlasOptions);
+        const mesh = new InstancedSpriteMesh(this, atlas.texture);
+        mesh.depthTest = this._depthTest;
+        mesh.depthWrite = this._depthWrite;
+        if (this._reservedCapacity !== undefined) {
+            mesh.reserve(this._reservedCapacity);
+        }
+        super.add(mesh);
+        return { atlas, mesh };
+    }
     /**
      * InstancedSprite实例数组
      * @type {Array<InstancedSprite>}
@@ -147,7 +248,7 @@ class InstancedSpriteCollection extends Object3D {
     }
     /**
      * 根据索引获取InstancedSprite实例
-     * @param {number} index 
+     * @param {number} index
      * @returns {InstancedSprite|undefined}
     */
     get(index) {
@@ -159,19 +260,17 @@ class InstancedSpriteCollection extends Object3D {
      * @returns {InstancedSprite|undefined}
     */
     getByUuid(uuid) {
-        for (const sprite of this._instancedSprites) {
-            if (sprite.uuid === uuid)
-                return sprite;
-        }
+        return this._spriteByUuid.get(uuid);
     }
     /**
      * 添加InstancedSprite
-     * @type {InstancedSpriteConstructorOptions} options
+     * @param {InstancedSpriteOptions} options - 初始化配置项
      * @returns {InstancedSprite}
     */
     add(options = {}) {
         const sprite = new InstancedSprite(options, this);
         this._instancedSprites.push(sprite);
+        this._spriteByUuid.set(sprite.uuid, sprite);
         return sprite;
     }
     /**
@@ -183,12 +282,13 @@ class InstancedSpriteCollection extends Object3D {
         const index = this._instancedSprites.indexOf(sprite);
         if (index !== -1) {
             this._instancedSprites.splice(index, 1);
+            this._spriteByUuid.delete(sprite.uuid);
             sprite._remove();
         }
         return this;
     }
     /**
-     * 移除所有InstancedSprite，并清空所有Mesh的实例数据（Mesh本身保留以便复用）
+     * 移除所有InstancedSprite，并清空所有Mesh的实例数据（Mesh与图集保留以便复用）
      * @returns {InstancedSpriteCollection}
     */
     clear() {
@@ -197,9 +297,22 @@ class InstancedSpriteCollection extends Object3D {
             sprite._instanceIndex = -1;
         }
         this._instancedSprites.length = 0;
-        const meshes = this._meshes.values();
-        for (const mesh of meshes) {
-            mesh.clear();
+        this._spriteByUuid.clear();
+        for (const entry of this._atlasList) {
+            entry.mesh.clear();
+        }
+        return this;
+    }
+    /**
+     * 预分配所有Mesh的容量，避免后续动态扩容
+     * @param {number} capacity - 需要预留的实例数量
+     * @returns {InstancedSpriteCollection}
+    */
+    reserve(capacity) {
+        Check.typeOf.number('capacity', capacity);
+        this._reservedCapacity = capacity;
+        for (const entry of this._atlasList) {
+            entry.mesh.reserve(capacity);
         }
         return this;
     }
@@ -219,24 +332,43 @@ class InstancedSpriteCollection extends Object3D {
      * @param {Array<Object>} intersects - The target array that holds the intersection points.
      */
     raycast(raycaster, intersects) {
-        const meshes = this._meshes.values();
-        for (const mesh of meshes) {
-            mesh.raycast(raycaster, intersects);
+        for (const entry of this._atlasList) {
+            entry.mesh.raycast(raycaster, intersects);
         }
     }
     /**
      * 每帧更新
      * @private
-     */
+    */
     update() {
         if (!this.visible) return;
 
-        const meshes = this._meshes.values();
-        for (const mesh of meshes) {
-            mesh.update();
+        for (const entry of this._atlasList) {
+            entry.mesh.update();
         }
     }
+    /**
+     * 释放所有 GPU 资源（几何体、材质、图集纹理），并移除所有子 Mesh
+     * @returns {InstancedSpriteCollection}
+    */
+    dispose() {
+        this.clear();
+        for (const entry of this._atlasList) {
+            entry.mesh.dispose();
+            entry.atlas.texture.dispose();
+        }
+        this._atlasList.length = 0;
+        this._imageEntry.clear();
+        super.clear();
+        return this;
+    }
 };
 
 export default InstancedSpriteCollection;
-export { InstancedSpriteCollection };
+export { InstancedSpriteCollection };
+/**
+ * InstancedSpriteCollection 的别名。
+ * @class
+ * @name BillboardCollection
+ */
+export const BillboardCollection = InstancedSpriteCollection;

package/src/InstancedSpriteMaterial.js

@@ -14,6 +14,7 @@ attribute vec4 aCenterAndSize; // xy: 锚点中心(0-1), zw: 图片宽高(像素
 attribute vec3 aScaleAndRotationAndSizeAttenuation; // x: 缩放, y: 旋转(弧度), z: 大小跟随相机深度(0/1)
 attribute vec4 aColorAndOpacity; // RGBA颜色
 attribute vec4 aPickColorAndEnabled; // xyz：拾取颜色，w：是否启用拾取颜色(0/1)
+attribute vec4 aUvRect; // xy: UV偏移, zw: UV缩放（非图集模式为(0,0,1,1)）
 
 varying float vShow;
 varying vec2 vUv;
@@ -31,7 +32,7 @@ void main() {
 
     // --- 2. 输出varying变量 ---
     vShow = show;
-    vUv = uv;
+    vUv = aUvRect.xy + uv * aUvRect.zw;
     vColorAndOpacity = aColorAndOpacity;
     vPickColorAndEnabled = aPickColorAndEnabled;
 
@@ -144,4 +145,10 @@ class InstancedSpriteMaterial extends ShaderMaterial {
 };
 
 export default InstancedSpriteMaterial;
-export { InstancedSpriteMaterial };
+export { InstancedSpriteMaterial };
+/**
+ * InstancedSpriteMaterial 的别名。
+ * @class
+ * @name BillboardMaterial
+ */
+export const BillboardMaterial = InstancedSpriteMaterial;