@lijuhong1981/three.instancedsprite 1.1.0 → 2.0.1

package/src/InstancedSpriteMesh.js

@@ -49,10 +49,35 @@ const AttributesItemSize = Object.freeze({
     aScaleAndRotationAndSizeAttenuation: 3,
     aColorAndOpacity: 4,
     aPickColorAndEnabled: 4,
+    aUvRect: 4,
 });
+/**
+ * 将指定实例的属性片段标记为需要更新，仅上传该实例对应的数据范围（增量上传）
+ * @param {InstancedSpriteMesh} mesh
+ * @param {string} name - attribute名称
+ * @param {number} index - 实例索引
+ * @param {number} itemSize - 单个实例占用的float数量
+ * @ignore
+*/
+function markUpdateRange(mesh, name, index, itemSize) {
+    const attribute = mesh.geometry.attributes[name];
+    attribute.addUpdateRange(index * itemSize, itemSize);
+    attribute.needsUpdate = true;
+}
+/**
+ * 将指定实例属性标记为全量更新（整块重传）
+ * @param {InstancedSpriteMesh} mesh
+ * @param {string} name - attribute名称
+ * @ignore
+*/
+function markFullUpdate(mesh, name) {
+    const attribute = mesh.geometry.attributes[name];
+    attribute.clearUpdateRanges();
+    attribute.needsUpdate = true;
+}
 /**
  * 检查并更新一个InstancedSprite实例的数据到对应的InstancedBufferAttribute位置
- * @param {InstancedSpriteMesh} mesh 
+ * @param {InstancedSpriteMesh} mesh
  * @param {InstancedSprite} sprite
  * @ignore
 */
@@ -71,6 +96,7 @@ function checkAndUpdateInstancedSprite(mesh, sprite) {
     const opacityChanged = (sprite._opacity !== sprite.opacity);
     const pickColorChanged = (sprite._pickColor.equals(sprite.pickColor) === false);
     const enablePickColorChanged = (sprite._enablePickColor !== sprite.enablePickColor);
+    const uvRectChanged = (sprite._uvRect.equals(sprite.uvRect) === false);
 
     let idx = 0;
 
@@ -86,7 +112,7 @@ function checkAndUpdateInstancedSprite(mesh, sprite) {
             sprite._show = sprite.show;
             attributesData.aPositionAndShow[idx + 3] = sprite._show ? 1 : 0;
         }
-        mesh.geometry.attributes.aPositionAndShow.needsUpdate = true;
+        markUpdateRange(mesh, 'aPositionAndShow', index, AttributesItemSize.aPositionAndShow);
     }
 
     if (centerChanged || imageSizeChanged) {
@@ -101,7 +127,7 @@ function checkAndUpdateInstancedSprite(mesh, sprite) {
             attributesData.aCenterAndSize[idx + 2] = sprite._imageSize.x;
             attributesData.aCenterAndSize[idx + 3] = sprite._imageSize.y;
         }
-        mesh.geometry.attributes.aCenterAndSize.needsUpdate = true;
+        markUpdateRange(mesh, 'aCenterAndSize', index, AttributesItemSize.aCenterAndSize);
     }
 
     if (scaleChanged || rotationChanged || sizeAttenuationChanged) {
@@ -118,7 +144,7 @@ function checkAndUpdateInstancedSprite(mesh, sprite) {
             sprite._sizeAttenuation = sprite.sizeAttenuation;
             attributesData.aScaleAndRotationAndSizeAttenuation[idx + 2] = sprite._sizeAttenuation ? 1 : 0;
         }
-        mesh.geometry.attributes.aScaleAndRotationAndSizeAttenuation.needsUpdate = true;
+        markUpdateRange(mesh, 'aScaleAndRotationAndSizeAttenuation', index, AttributesItemSize.aScaleAndRotationAndSizeAttenuation);
     }
 
     if (colorChanged || opacityChanged) {
@@ -133,7 +159,7 @@ function checkAndUpdateInstancedSprite(mesh, sprite) {
             sprite._opacity = sprite.opacity;
             attributesData.aColorAndOpacity[idx + 3] = sprite._opacity;
         }
-        mesh.geometry.attributes.aColorAndOpacity.needsUpdate = true;
+        markUpdateRange(mesh, 'aColorAndOpacity', index, AttributesItemSize.aColorAndOpacity);
     }
 
     if (pickColorChanged || enablePickColorChanged) {
@@ -148,14 +174,24 @@ function checkAndUpdateInstancedSprite(mesh, sprite) {
             sprite._enablePickColor = sprite.enablePickColor;
             attributesData.aPickColorAndEnabled[idx + 3] = sprite._enablePickColor ? 1 : 0;
         }
-        mesh.geometry.attributes.aPickColorAndEnabled.needsUpdate = true;
+        markUpdateRange(mesh, 'aPickColorAndEnabled', index, AttributesItemSize.aPickColorAndEnabled);
+    }
+
+    if (uvRectChanged) {
+        idx = index * AttributesItemSize.aUvRect;
+        sprite._uvRect.copy(sprite.uvRect);
+        attributesData.aUvRect[idx] = sprite._uvRect.x;
+        attributesData.aUvRect[idx + 1] = sprite._uvRect.y;
+        attributesData.aUvRect[idx + 2] = sprite._uvRect.z;
+        attributesData.aUvRect[idx + 3] = sprite._uvRect.w;
+        markUpdateRange(mesh, 'aUvRect', index, AttributesItemSize.aUvRect);
     }
 };
 /**
  * 添加一个InstancedSprite实例的数据到InstancedBufferAttribute中对应的位置
  * @param {InstancedSpriteMesh} mesh
  * @param {InstancedSprite} sprite
- * @param {number} index 
+ * @param {number} index
  * @ignore
 */
 function addInstancedSprite(mesh, sprite, index) {
@@ -170,7 +206,7 @@ function addInstancedSprite(mesh, sprite, index) {
     attributesData.aPositionAndShow[idx + 2] = sprite._position.z;
     sprite._show = sprite.show;
     attributesData.aPositionAndShow[idx + 3] = sprite._show ? 1 : 0;
-    mesh.geometry.attributes.aPositionAndShow.needsUpdate = true;
+    markFullUpdate(mesh, 'aPositionAndShow');
 
     idx = index * AttributesItemSize.aCenterAndSize;
     sprite._center.copy(sprite.center);
@@ -179,7 +215,7 @@ function addInstancedSprite(mesh, sprite, index) {
     sprite._imageSize.copy(sprite.imageSize);
     attributesData.aCenterAndSize[idx + 2] = sprite._imageSize.x;
     attributesData.aCenterAndSize[idx + 3] = sprite._imageSize.y;
-    mesh.geometry.attributes.aCenterAndSize.needsUpdate = true;
+    markFullUpdate(mesh, 'aCenterAndSize');
 
     idx = index * AttributesItemSize.aScaleAndRotationAndSizeAttenuation;
     sprite._scale = sprite.scale;
@@ -188,7 +224,7 @@ function addInstancedSprite(mesh, sprite, index) {
     attributesData.aScaleAndRotationAndSizeAttenuation[idx + 1] = sprite._rotation;
     sprite._sizeAttenuation = sprite.sizeAttenuation;
     attributesData.aScaleAndRotationAndSizeAttenuation[idx + 2] = sprite._sizeAttenuation ? 1 : 0;
-    mesh.geometry.attributes.aScaleAndRotationAndSizeAttenuation.needsUpdate = true;
+    markFullUpdate(mesh, 'aScaleAndRotationAndSizeAttenuation');
 
     idx = index * AttributesItemSize.aColorAndOpacity;
     sprite._color.copy(sprite.color);
@@ -197,18 +233,28 @@ function addInstancedSprite(mesh, sprite, index) {
     attributesData.aColorAndOpacity[idx + 2] = sprite._color.b;
     sprite._opacity = sprite.opacity;
     attributesData.aColorAndOpacity[idx + 3] = sprite._opacity;
-    mesh.geometry.attributes.aColorAndOpacity.needsUpdate = true;
+    markFullUpdate(mesh, 'aColorAndOpacity');
+
+    idx = index * AttributesItemSize.aUvRect;
+    sprite._uvRect.copy(sprite.uvRect);
+    attributesData.aUvRect[idx] = sprite._uvRect.x;
+    attributesData.aUvRect[idx + 1] = sprite._uvRect.y;
+    attributesData.aUvRect[idx + 2] = sprite._uvRect.z;
+    attributesData.aUvRect[idx + 3] = sprite._uvRect.w;
+    markFullUpdate(mesh, 'aUvRect');
 };
 
 /**
  * InstancedSpriteMesh类，基于InstancedBufferGeometry实现的高性能InstancedSprite渲染组件
- * 
+ *
+ * 一张图集纹理对应一个 InstancedSpriteMesh，所有使用该图集的 Sprite 由其统一绘制
+ *
  * @extends {Mesh}
 */
 class InstancedSpriteMesh extends Mesh {
     /**
      * @param {InstancedSpriteCollection} collection - 所属的InstancedSpriteCollection实例，必填
-     * @param {Texture} texture - 材质图像纹理，必填
+     * @param {Texture} texture - 图集纹理，必填
      * @constructor
     */
     constructor(collection, texture) {
@@ -223,6 +269,12 @@ class InstancedSpriteMesh extends Mesh {
          * @readonly
         */
         this.type = "InstancedSpriteMesh";
+        /**
+         * 实例化几何体的包围球基于单位四边形（位于原点），不包含实例位置，视锥剔除会把远离原点的实例整批误剔除，因此禁用
+         * @type {boolean}
+         * @default false
+        */
+        this.frustumCulled = false;
         /**
          * @type {Array<InstancedSprite>}
          * @ignore
@@ -250,7 +302,9 @@ class InstancedSpriteMesh extends Mesh {
          * @ignore
         */
         this._maxCapacity = 0;
-        this._enaureCapacity(64);
+        this._ensureCapacity(1024);
+        // 初始无实例，绘制数量为0（_ensureCapacity 只负责扩容，不改变实例数量）
+        this.geometry.instanceCount = 0;
     }
     /**
      * InstancedSpriteMesh对象标识
@@ -268,6 +322,16 @@ class InstancedSpriteMesh extends Mesh {
         Check.typeOf.boolean('depthTest', value);
         this.material.depthTest = value;
     }
+    /**
+     * 深度写入开关，默认为true；多个半透明 Sprite 重叠时，开启深度写入可能导致排序瑕疵（后方 Sprite 被错误遮挡），关闭可缓解，适合半透明标签/粒子等场景
+     * @type {boolean}
+     * @default true
+    */
+    get depthWrite() { return this.material.depthWrite; }
+    set depthWrite(value) {
+        Check.typeOf.boolean('depthWrite', value);
+        this.material.depthWrite = value;
+    }
     /**
      * InstancedSprite对象数组
      * @type {Array<InstancedSprite>}
@@ -279,30 +343,36 @@ class InstancedSpriteMesh extends Mesh {
      * @param {number} required - 需要容纳的InstancedSprite数量
      * @private
     */
-    _enaureCapacity(required) {
-        if (required < this._maxCapacity) return;
+    _ensureCapacity(required) {
+        if (required <= this._maxCapacity) return;
 
-        const newCapacity = Math.max(required, this._maxCapacity + 64);
+        // 线性扩容（+1024）保证内存浪费有界；Three.js 不支持原地扩容 buffer，需新建数组与 attribute
+        const newCapacity = Math.max(required, this._maxCapacity + 1024);
 
         for (const [name, itemSize] of Object.entries(AttributesItemSize)) {
-            const newArray = new Float32Array(newCapacity * itemSize);
             const oldArray = this._attributesData[name];
+            const newArray = new Float32Array(newCapacity * itemSize);
             if (oldArray) {
-                const copyLen = Math.min(oldArray.length, newArray.length);
-                newArray.set(oldArray.subarray(0, copyLen));
+                newArray.set(oldArray.subarray(0, Math.min(oldArray.length, newArray.length)));
             }
             this._attributesData[name] = newArray;
-        }
 
-        // 创建 InstancedBufferAttribute 对象
-        for (const [name, itemSize] of Object.entries(AttributesItemSize)) {
-            const attr = new InstancedBufferAttribute(this._attributesData[name], itemSize);
-            this.geometry.setAttribute(name, attr);
+            const attribute = new InstancedBufferAttribute(newArray, itemSize);
+            this.geometry.setAttribute(name, attribute);
         }
 
-        this.geometry.instanceCount = required;
         this._maxCapacity = newCapacity;
     }
+    /**
+     * 预分配容量，避免后续动态扩容（不改变当前实际绘制的实例数量）
+     * @param {number} capacity - 需要预留的实例数量
+     * @returns {InstancedSpriteMesh}
+    */
+    reserve(capacity) {
+        Check.typeOf.number('capacity', capacity);
+        this._ensureCapacity(capacity);
+        return this;
+    }
     /**
      * 添加一个InstancedSprite
      * @param {InstancedSprite} sprite - 要添加的InstancedSprite实例
@@ -369,33 +439,40 @@ class InstancedSpriteMesh extends Mesh {
 
         // 计算最终需要的容量
         const requiredCapacity = instancedSprites.length + addInstancedSprites.length - removeInstancedSprites.length;
-        this._enaureCapacity(requiredCapacity);
+        this._ensureCapacity(requiredCapacity);
 
         if (removeInstancedSprites.length > 0) {
-            // 如果有需要移除的InstancedSprite，先从instancedSprites数组中移除
+            // 末位换入（swap-and-pop）移除：把最后一个 sprite 换到被移除的位置，O(k) 而非 O(n) 全量重写
+            const movedSprites = [];
             for (const sprite of removeInstancedSprites) {
-                const index = instancedSprites.indexOf(sprite);
-                if (index !== -1) {
-                    instancedSprites.splice(index, 1); //从instancedSprites数组中移除
-                    sprite._mesh = undefined;
-                    sprite._instanceIndex = -1;
+                const index = sprite._instanceIndex;
+                if (index === -1)
+                    continue; // 已被处理过（例如换入后又在本帧被移除）
+
+                const last = instancedSprites[instancedSprites.length - 1];
+                instancedSprites.pop();
+                if (last !== sprite) {
+                    instancedSprites[index] = last;
+                    last._instanceIndex = index; // 立即更新，避免后续删除用到陈旧索引
+                    movedSprites.push(last);
                 }
-                // else
-                //     console.warn('InstancedSprite not found in InstancedSpriteMesh during removal');
+                sprite._instanceIndex = -1;
+                sprite._mesh = undefined;
             }
             removeInstancedSprites.length = 0;
 
-            // 如果有需要添加的InstancedSprite，则加入instancedSprites数组中
-            if (addInstancedSprites.length > 0) {
-                instancedSprites.push(...addInstancedSprites);
-                addInstancedSprites.length = 0;
+            // 重写被移动 sprite 的数据到新位置
+            for (const sprite of movedSprites) {
+                if (sprite._instanceIndex !== -1) {
+                    addInstancedSprite(this, sprite, sprite._instanceIndex);
+                }
             }
 
-            // 重新写入所有InstancedSprite的属性数据到InstancedBufferAttribute中
-            const length = instancedSprites.length;
-            for (let i = 0; i < length; i++) {
-                const sprite = instancedSprites[i];
-                addInstancedSprite(this, sprite, i);
+            // 添加新 sprite
+            while (addInstancedSprites.length > 0) {
+                const sprite = addInstancedSprites.shift();
+                addInstancedSprite(this, sprite, instancedSprites.length);
+                instancedSprites.push(sprite);
             }
         } else {
             // 检查并更新属性值有变化的InstancedSprite
@@ -413,6 +490,9 @@ class InstancedSpriteMesh extends Mesh {
 
         this.geometry.instanceCount = instancedSprites.length; //更新instanceCount
     }
+    /**
+     * 释放 GPU 资源
+    */
     dispose() {
         this.clear();
         this.geometry.dispose();
@@ -422,4 +502,9 @@ class InstancedSpriteMesh extends Mesh {
 
 export default InstancedSpriteMesh;
 export { InstancedSpriteMesh };
-
+/**
+ * InstancedSpriteMesh 的别名。
+ * @class
+ * @name BillboardMesh
+ */
+export const BillboardMesh = InstancedSpriteMesh;

package/src/InstancedSpriteNodeMaterial.js

@@ -43,6 +43,7 @@ class InstancedSpriteNodeMaterial extends NodeMaterial {
         const aScaleAndRotationAndSizeAttenuation = attribute('aScaleAndRotationAndSizeAttenuation', 'vec3');
         const aColorAndOpacity = attribute('aColorAndOpacity', 'vec4');
         const aPickColorAndEnabled = attribute('aPickColorAndEnabled', 'vec4');
+        const aUvRect = attribute('aUvRect', 'vec4');
 
         // ============================================================
         // Varying 变量 — 从顶点着色器传递到片元着色器
@@ -67,7 +68,7 @@ class InstancedSpriteNodeMaterial extends NodeMaterial {
             // --- 2. 输出 varying ---
             vShow.assign(show);
             vColorAndOpacity.assign(aColorAndOpacity);
-            vUv.assign(uv());
+            vUv.assign(aUvRect.xy.add(uv().mul(aUvRect.zw)));
             vPickColorAndEnabled.assign(aPickColorAndEnabled);
 
             // --- 3. 计算模型视图位置 ---
@@ -84,8 +85,8 @@ class InstancedSpriteNodeMaterial extends NodeMaterial {
 
             If(isVisible, () => {
                 // --- 4. sizeAttenuation：大小跟随相机深度 ---
-                // 检查是否为透视投影: 透视投影矩阵中 m[2][3] (elements[11]) == -1
-                const scaleFactor = sizeAttenuation.lessThan(0.5).and(cameraProjectionMatrix.element(11).equal(-1))
+                // 检查是否为透视投影：透视投影矩阵 m[2][3] (elements[11]) == -1
+                const scaleFactor = sizeAttenuation.lessThan(0.5).and(cameraProjectionMatrix.element(2).w.equal(-1))
                     .select(scale.mul(depth), scale);
 
                 // --- 5. 坐标对齐 ---
@@ -119,7 +120,7 @@ class InstancedSpriteNodeMaterial extends NodeMaterial {
             });
 
             return clipPosition;
-        }).once();
+        }).once()();
 
         // ============================================================
         // 片元着色器 (fragmentNode)
@@ -145,7 +146,7 @@ class InstancedSpriteNodeMaterial extends NodeMaterial {
             });
 
             return diffuseColor;
-        }).once();
+        }).once()();
     }
     /**
      * 图片纹理
@@ -161,3 +162,9 @@ class InstancedSpriteNodeMaterial extends NodeMaterial {
 
 export default InstancedSpriteNodeMaterial;
 export { InstancedSpriteNodeMaterial };
+/**
+ * InstancedSpriteNodeMaterial 的别名。
+ * @class
+ * @name BillboardNodeMaterial
+ */
+export const BillboardNodeMaterial = InstancedSpriteNodeMaterial;

package/src/TextureAtlas.js

@@ -0,0 +1,125 @@
+import { CanvasTexture } from "three";
+
+/**
+ * 纹理图集，将多张图片按行（shelf）打包进一张 Canvas 纹理，用于合并 draw call
+ */
+class TextureAtlas {
+    /**
+     * @param {object} [options]
+     * @param {number} [options.initialSize=1024] 初始边长（正方形，单位像素）
+     * @param {number} [options.maxSize=8192] 最大边长，自动扩容到该值后不再增大
+     * @param {number} [options.padding=2] 子图间距，防止线性过滤时边缘渗色
+    */
+    constructor(options = {}) {
+        this.initialSize = options.initialSize || 1024;
+        this.maxSize = options.maxSize || 8192;
+        this.padding = options.padding !== undefined ? options.padding : 2;
+
+        this.size = this.initialSize;
+        this.canvas = document.createElement('canvas');
+        this.canvas.width = this.size;
+        this.canvas.height = this.size;
+        this.ctx = this.canvas.getContext('2d');
+
+        this.texture = new CanvasTexture(this.canvas);
+        this.texture.needsUpdate = true;
+
+        this._cursorX = this.padding;
+        this._cursorY = this.padding;
+        this._rowHeight = 0;
+        this._rects = new Map(); // source -> {x, y, w, h} 像素矩形
+    }
+    /**
+     * 将图片加入图集，返回其像素矩形；已加入过则返回缓存；图集整体已满则返回null
+     * @param {HTMLImageElement|HTMLCanvasElement} source
+     * @returns {{x:number,y:number,w:number,h:number}|null}
+    */
+    add(source) {
+        const cached = this._rects.get(source);
+        if (cached) return cached;
+
+        const w = source.width;
+        const h = source.height;
+        const stepW = w + this.padding * 2;
+        const stepH = h + this.padding * 2;
+
+        // 单张图片超过当前图集尺寸时，先扩容到能容纳
+        while (stepW > this.size || stepH > this.size) {
+            if (!this.grow()) {
+                throw new Error('TextureAtlas: 图片尺寸超过图集最大尺寸');
+            }
+        }
+
+        // 当前行放不下则换行
+        if (this._cursorX + stepW > this.size) {
+            this._cursorX = this.padding;
+            this._cursorY += this._rowHeight;
+            this._rowHeight = 0;
+        }
+        // 图集整体已满
+        if (this._cursorY + stepH > this.size) {
+            return null;
+        }
+
+        const x = this._cursorX + this.padding;
+        const y = this._cursorY + this.padding;
+        const rect = { x, y, w, h };
+        this._rects.set(source, rect);
+
+        this.ctx.drawImage(source, x, y, w, h);
+
+        this._cursorX += stepW;
+        this._rowHeight = Math.max(this._rowHeight, stepH);
+
+        this.texture.needsUpdate = true;
+        return rect;
+    }
+    /**
+     * 获取图片已分配的像素矩形
+     * @param {HTMLImageElement|HTMLCanvasElement} source
+     * @returns {{x:number,y:number,w:number,h:number}|undefined}
+    */
+    getRect(source) {
+        return this._rects.get(source);
+    }
+    /**
+     * 扩容图集（边长翻倍），成功返回true；已达最大尺寸返回false
+     * @returns {boolean}
+    */
+    grow() {
+        const newSize = this.size * 2;
+        if (newSize > this.maxSize) return false;
+
+        const newCanvas = document.createElement('canvas');
+        newCanvas.width = newSize;
+        newCanvas.height = newSize;
+        const newCtx = newCanvas.getContext('2d');
+        newCtx.drawImage(this.canvas, 0, 0);
+
+        this.canvas = newCanvas;
+        this.ctx = newCtx;
+        this.size = newSize;
+
+        // 尺寸变化必须重建纹理：WebGL2 用 texStorage 分配固定尺寸，替换 image 后 texSubImage2D 无法扩容
+        this.texture.dispose();
+        this.texture = new CanvasTexture(this.canvas);
+        this.texture.needsUpdate = true;
+        return true;
+    }
+    /**
+     * 将像素矩形转为归一化 UV（uOffset, vOffset, uScale, vScale）
+     * @param {{x:number,y:number,w:number,h:number}} rect
+     * @returns {Array<number>}
+    */
+    getUvRect(rect) {
+        return [
+            rect.x / this.size,
+            1 - (rect.y + rect.h) / this.size, // flipY=true 时纹理上下翻转，v 坐标需反转
+            rect.w / this.size,
+            rect.h / this.size,
+        ];
+    }
+}
+
+export default TextureAtlas;
+export { TextureAtlas };

package/.gitattributes

@@ -1,2 +0,0 @@
-*.js text eol=lf
-*.md text eol=lf