@lijuhong1981/three.instancedsprite 1.0.1 → 1.1.0

package/.gitattributes

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

package/API.md

@@ -282,6 +282,7 @@ InstancedSpriteCollection类，批量管理InstancedSprite实例
     * [.getByUuid(uuid)](#InstancedSpriteCollection+getByUuid) ⇒ [<code>InstancedSprite</code>](#InstancedSprite) \| <code>undefined</code>
     * [.add()](#InstancedSpriteCollection+add) ⇒ [<code>InstancedSprite</code>](#InstancedSprite)
     * [.remove(sprite)](#InstancedSpriteCollection+remove) ⇒ [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)
+    * [.clear()](#InstancedSpriteCollection+clear) ⇒ [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)
     * [.forEach(callback)](#InstancedSpriteCollection+forEach) ⇒ [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)
     * [.raycast(raycaster, intersects)](#InstancedSpriteCollection+raycast)
 
@@ -385,6 +386,12 @@ InstancedSprite实例数量
 | --- | --- |
 | sprite | [<code>InstancedSprite</code>](#InstancedSprite) | 
 
+<a name="InstancedSpriteCollection+clear"></a>
+
+### instancedSpriteCollection.clear() ⇒ [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)
+移除所有InstancedSprite，并清空所有Mesh的实例数据（Mesh本身保留以便复用）
+
+**Kind**: instance method of [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)  
 <a name="InstancedSpriteCollection+forEach"></a>
 
 ### instancedSpriteCollection.forEach(callback) ⇒ [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)

package/README.md

@@ -1,55 +1,125 @@
-# InstancedSprite
-
-three自带的Sprite并不支持GPU实例化渲染，当遇到需要在场景中大量展示标签的情况时就会出现帧率下降的问题，所以开发了这个InstancedSprite，以InstancedBufferGeometry+自定义ShaderMaterial的形式实例化渲染InstancedSprite对象，极大的提高了大批量标签展示时的渲染效率。
-
-## 安装
-
-```bash
-npm install @lijuhong1981/three.instancedsprite
-```
-
-## 使用
-
-```js
-import { InstancedSpriteCollection } from "@lijuhong1981/instancedsprite";
-...
-// 初始化
-const collection = new InstancedSpriteCollection();
-// 如果使用的是WebGPURenderer，请添加参数true，以启用TSL的NodeMaterial
-// const collection = new InstancedSpriteCollection(true);
-...
-// 动画帧更新
-const onAnimate = () => {
-    window.requestAnimationFrame(onAnimate);
-    ...
-    // 每帧更新
-    collection.update();
-};
-// 添加
-const sprite = collection.add(
-    {
-        position: [100, 100, 100], //位置
-        rotation: 0, //旋转
-        scale: 1.0, //缩放
-        sizeAttenuation: false, //尺寸跟随相机深度变化
-        center: [0.5, 0], //中心锚点
-        color: 0xff0000, //颜色
-        opacity: 0.5, //不透明度
-        image: './res/icon.png', //图像地址，相同的image会分配到同一个Mesh下一次性渲染
-    }
-);
-// 移除
-sprite.remove();
-// 或
-// collection.remove(sprite);
-// 清空
-collection.clear();
-// 射线检测
-raycaster.setFromCamera(ndc, camera)
-const intersects = raycaster.intersectObject(collection);
-if (intersects.length > 0) {
-    const pickedSprite = intersects[0].object; //拾取到的InstancedSprite对象
-}
-```
-
-## [API文档](./API.md)
+# InstancedSprite
+
+Three.js 自带的 `Sprite` 不支持 GPU 实例化渲染。当场景中需要同时展示大量标签、图标或提示时，逐个绘制 `Sprite` 会产生大量 draw call，导致帧率明显下降。
+
+`InstancedSprite` 基于 `InstancedBufferGeometry` + 自定义 `ShaderMaterial`（或 TSL `NodeMaterial`）实现实例化渲染。**相同图片的 Sprite 会自动合并到同一个 Mesh，一次 draw call 全部绘制**，极大提升大批量标签的渲染效率。
+
+## 特性
+
+- 🚀 **GPU 实例化**：基于 `InstancedBufferGeometry`，数千个 Sprite 仅需一次 draw call
+- 🏷️ **按图自动合批**：`image` 相同的 Sprite 自动归入同一个 `InstancedSpriteMesh` 统一渲染
+- ✏️ **属性自动同步**：直接修改 Sprite 的 `position` / `rotation` / `scale` / `color` 等属性，每帧 `update()` 时通过脏检查自动上传至 GPU，无需手动刷新
+- 🎯 **射线拾取**：内置射线检测，可直接用 `Raycaster` 拾取到具体的 `InstancedSprite` 实例
+- 🖼️ **像素级透明**：片元着色器自动丢弃完全透明的像素
+- 🎨 **双渲染后端**：同时支持 WebGL（GLSL `ShaderMaterial`）与 WebGPU（TSL `NodeMaterial`）
+- 📏 **动态扩容**：实例缓冲区按需自动扩容，实例数量无硬性上限
+
+## 安装
+
+```bash
+npm install @lijuhong1981/three.instancedsprite
+```
+
+依赖 `three`（`>= 0.171.0`）。若使用 WebGPU / TSL 材质，需从 `three/webgpu` 引入相关构建。
+
+## 使用
+
+```js
+import * as THREE from "three";
+import { InstancedSpriteCollection } from "@lijuhong1981/three.instancedsprite";
+
+// 初始化（继承自 Object3D，直接加入场景）
+const collection = new InstancedSpriteCollection();
+scene.add(collection);
+
+// 若使用 WebGPURenderer，传入 true 以启用 TSL 的 NodeMaterial
+// const collection = new InstancedSpriteCollection(true);
+
+// 每帧更新：内部做脏检查，把发生变化的属性同步到 GPU
+const onAnimate = () => {
+    window.requestAnimationFrame(onAnimate);
+    collection.update();
+};
+
+// 添加一个 Sprite
+const sprite = collection.add({
+    position: [100, 100, 100],   // 位置（世界空间）
+    rotation: 0,                 // 旋转（弧度）
+    scale: 1.0,                  // 缩放
+    sizeAttenuation: false,      // 尺寸是否跟随相机深度变化（默认 true）
+    center: [0.5, 0],            // 中心锚点（0-1，默认 (0.5, 0.5)）
+    color: 0xff0000,             // 颜色（默认 0xffffff）
+    opacity: 0.5,                // 不透明度（0-1，默认 1）
+    image: './res/icon.png',     // 图片地址，相同 image 会合并到同一个 Mesh 一次渲染
+});
+
+// 运行时修改属性（无需手动刷新，update() 会自动同步）
+sprite.position.set(200, 100, 0);
+sprite.color.set(0x00ff00);
+sprite.show = false;             // 隐藏（等同于 sprite.visible）
+
+// 移除
+sprite.remove();
+// 或
+collection.remove(sprite);
+
+// 清空所有 Sprite
+collection.clear();
+
+// 射线检测
+const ndc = new THREE.Vector2(/* ... */);
+raycaster.setFromCamera(ndc, camera);
+const intersects = raycaster.intersectObject(collection);
+if (intersects.length > 0) {
+    const pickedSprite = intersects[0].object; // 拾取到的 InstancedSprite
+    const instanceId = intersects[0].instanceId; // 实例索引
+}
+```
+
+## 主要 API
+
+| 类 | 说明 |
+| --- | --- |
+| `InstancedSpriteCollection` | 继承自 `Object3D`，批量管理所有 Sprite；按 `image` 分组并生成对应的 `InstancedSpriteMesh` |
+| `InstancedSprite` | 数据模型类，保存单个 Sprite 的全部属性；**不继承 `Object3D`**，不能直接加入 Scene，由 Collection 统一渲染 |
+| `InstancedSpriteMesh` | 继承自 `Mesh`，基于 `InstancedBufferGeometry`，同一图片的所有 Sprite 由其统一绘制 |
+| `InstancedSpriteMaterial` | 继承自 `ShaderMaterial`，以 instanced attribute 形式接收每个 Sprite 的属性（WebGL） |
+| `InstancedSpriteNodeMaterial` | 继承自 `NodeMaterial`，基于 TSL 实现，功能与 `InstancedSpriteMaterial` 一致（WebGPU） |
+
+### InstancedSpriteCollection
+
+- `add(options)` → `InstancedSprite`：添加并返回一个 Sprite
+- `remove(sprite)`：移除指定 Sprite
+- `clear()`：移除所有 Sprite
+- `get(index)` / `getByUuid(uuid)`：按索引 / uuid 获取
+- `forEach(callback)`：遍历所有 Sprite
+- `update()`：每帧调用，同步属性变化
+- `raycast(raycaster, intersects)`：射线拾取
+- `instancedSprites`：Sprite 数组（只读）；`size`：数量（只读）
+- `depthTest`：深度测试开关（默认 `true`；关闭后所有 Sprite 始终渲染在最前，适合 UI 元素）
+
+### InstancedSprite 属性
+
+| 属性 | 类型 | 默认值 | 说明 |
+| --- | --- | --- | --- |
+| `position` | `Vector3` | `(0, 0, 0)` | 世界坐标位置 |
+| `scale` | `number` | `1` | 缩放 |
+| `rotation` | `number` | `0` | 旋转（弧度）；可用 `rotationDegrees` 以角度读写 |
+| `sizeAttenuation` | `boolean` | `true` | 尺寸是否跟随相机深度变化 |
+| `center` | `Vector2` | `(0.5, 0.5)` | 锚点中心（0-1） |
+| `color` | `Color` | `0xffffff` | 颜色 |
+| `opacity` | `number` | `1` | 不透明度（0-1） |
+| `show` / `visible` | `boolean` | `true` | 是否显示 |
+| `image` | `string \| HTMLImageElement \| HTMLCanvasElement` | - | 图片资源 |
+| `imageSize` / `imageWidth` / `imageHeight` | - | - | 图片尺寸，图片加载完成后可用（只读） |
+| `userData` | `object` | `{}` | 用户自定义数据 |
+| `uuid` | `string` | - | 唯一标识（只读） |
+
+## 工作原理
+
+1. `InstancedSpriteCollection.add()` 创建 `InstancedSprite` 数据对象，并根据其 `image` 找到（或新建）对应的 `InstancedSpriteMesh`。
+2. `InstancedSpriteMesh` 持有 `InstancedBufferGeometry`，为每个实例分配一组 instanced attribute（位置+显示、锚点+尺寸、缩放+旋转+衰减、颜色+透明度、拾取颜色）。
+3. 顶点着色器根据实例属性计算 billboard 位置（对齐、旋转、透视缩放），片元着色器采样纹理并应用颜色 / 透明度。
+4. 每帧调用 `update()`：仅当属性实际发生变化（脏检查）时才更新对应缓冲区，减少 CPU→GPU 传输开销；缓冲区按需自动扩容。
+
+## [API 文档](./API.md)

package/index.js

@@ -1,5 +1,5 @@
-export * from "./src/InstancedSprite.js";
-export * from "./src/InstancedSpriteCollection.js";
-export * from "./src/InstancedSpriteMaterial.js";
-export * from "./src/InstancedSpriteMesh.js";
-export * from "./src/InstancedSpriteNodeMaterial.js";
+export * from "./src/InstancedSprite.js";
+export * from "./src/InstancedSpriteCollection.js";
+export * from "./src/InstancedSpriteMaterial.js";
+export * from "./src/InstancedSpriteMesh.js";
+export * from "./src/InstancedSpriteNodeMaterial.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lijuhong1981/three.instancedsprite",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "",
   "type": "module",
   "module": "index.js",

package/src/InstancedSpriteCollection.js

@@ -187,6 +187,22 @@ class InstancedSpriteCollection extends Object3D {
         }
         return this;
     }
+    /**
+     * 移除所有InstancedSprite，并清空所有Mesh的实例数据（Mesh本身保留以便复用）
+     * @returns {InstancedSpriteCollection}
+    */
+    clear() {
+        for (const sprite of this._instancedSprites) {
+            sprite._mesh = undefined;
+            sprite._instanceIndex = -1;
+        }
+        this._instancedSprites.length = 0;
+        const meshes = this._meshes.values();
+        for (const mesh of meshes) {
+            mesh.clear();
+        }
+        return this;
+    }
     /**
      * 遍历所有的InstancedSprite
      * @param {Function} callback

package/src/InstancedSpriteMaterial.js

@@ -1,147 +1,147 @@
-import { ShaderMaterial, Texture } from "three";
-
-const vertexShader = `
-// Three.js ShaderMaterial专用，自动注入uv、position、modelViewMatrix、projectionMatrix
-precision highp float;
-precision highp int;
-
-#include <common>
-#include <logdepthbuf_pars_vertex>
-
-// 基础属性
-attribute vec4 aPositionAndShow; // xyz: InstancedSprite位置（世界空间），w：显示标志(0/1)
-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)
-
-varying float vShow;
-varying vec2 vUv;
-varying vec4 vColorAndOpacity;
-varying vec4 vPickColorAndEnabled;
-
-void main() {
-    // --- 1. 提前解包属性（GPU会自动优化，无性能损失）---
-    float show = aPositionAndShow.w;
-    float scale = aScaleAndRotationAndSizeAttenuation.x;
-    float rotation = aScaleAndRotationAndSizeAttenuation.y;
-    float sizeAttenuation = aScaleAndRotationAndSizeAttenuation.z;
-    vec2 center = aCenterAndSize.xy;
-    vec2 imageSize = aCenterAndSize.zw;
-
-    // --- 2. 输出varying变量 ---
-    vShow = show;
-    vUv = uv;
-    vColorAndOpacity = aColorAndOpacity;
-    vPickColorAndEnabled = aPickColorAndEnabled;
-
-    // --- 3. 提前隐藏不可见物体（顶点级丢弃，性能最优）---
-    if (show < 0.5 || imageSize.x <= 0.0 || imageSize.y <= 0.0) {
-        vShow = 0.0;
-        gl_Position = vec4(0.0, 0.0, 2.0, 1.0);
-        return;
-    }
-
-    // --- 4. 计算模型视图位置 ---
-    vec4 mvPosition = modelViewMatrix * vec4(aPositionAndShow.xyz, 1.0);
-
-    // --- 5. 深度检查：隐藏相机后面的物体，避免尺寸翻转 ---
-    float depth = -mvPosition.z;
-    if (depth <= 0.0) {
-        vShow = 0.0;
-        gl_Position = vec4(0.0, 0.0, 2.0, 1.0);
-        return;
-    }
-
-    // --- 6. sizeAttenuation检查：大小跟随深度
-    if (sizeAttenuation < 0.5) {
-        bool isPerspective = isPerspectiveMatrix( projectionMatrix );
-		if ( isPerspective ) scale *= depth;
-    }
-
-    // --- 7. 坐标对齐
-    float aspectRatio = imageSize.x / imageSize.y;
-    vec2 alignedPosition = ( position.xy - ( center - vec2( 0.5 ) ) ) * aspectRatio * scale;
-
-    // --- 8. 计算旋转
-	vec2 rotatedPosition;
-	rotatedPosition.x = cos( rotation ) * alignedPosition.x - sin( rotation ) * alignedPosition.y;
-	rotatedPosition.y = sin( rotation ) * alignedPosition.x + cos( rotation ) * alignedPosition.y;
-	mvPosition.xy += rotatedPosition;
-
-    // --- 9. 投影变换 ---
-    gl_Position = projectionMatrix * mvPosition;
-
-    #include <logdepthbuf_vertex>
-}
-`;
-
-const fragmentShader = `
-uniform sampler2D uTexture;
-
-#include <common>
-#include <logdepthbuf_pars_fragment>
-
-varying float vShow;
-varying vec2 vUv;
-varying vec4 vColorAndOpacity;
-varying vec4 vPickColorAndEnabled;
-
-void main() {
-    if (vShow < 0.5) {
-        discard;
-    }
-
-    float enablePickColor = vPickColorAndEnabled.w;
-
-    if (enablePickColor > 0.5){
-        gl_FragColor = vec4(vPickColorAndEnabled.xyz, 1.0);
-    } else {
-        vec4 texColor = texture2D(uTexture, vUv);
-        vec4 diffuseColor = texColor * vColorAndOpacity;
-
-        // 丢弃完全透明的像素
-        if (diffuseColor.a < 0.005) {
-            discard;
-        }
-
-        gl_FragColor = diffuseColor;
-        #include <logdepthbuf_fragment>
-        #include <tonemapping_fragment>
-	    #include <colorspace_fragment>
-    }
-}
-`;
-
-/**
- * InstancedSprite 材质类，以attribute形式传入InstancedSprite对象实例属性
- * 
- * @extends ShaderMaterial
-*/
-class InstancedSpriteMaterial extends ShaderMaterial {
-    constructor() {
-        super({
-            vertexShader,
-            fragmentShader,
-            uniforms: {
-                uTexture: { value: null },
-            },
-            transparent: true,
-            depthTest: true,
-            depthWrite: true,
-        });
-    }
-    /**
-     * 图片纹理
-     * @type {Texture}
-    */
-    set texture(value) {
-        this.uniforms.uTexture.value = value;
-    }
-    get texture() {
-        return this.uniforms.uTexture.value;
-    }
-};
-
-export default InstancedSpriteMaterial;
+import { ShaderMaterial, Texture } from "three";
+
+const vertexShader = `
+// Three.js ShaderMaterial专用，自动注入uv、position、modelViewMatrix、projectionMatrix
+precision highp float;
+precision highp int;
+
+#include <common>
+#include <logdepthbuf_pars_vertex>
+
+// 基础属性
+attribute vec4 aPositionAndShow; // xyz: InstancedSprite位置（世界空间），w：显示标志(0/1)
+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)
+
+varying float vShow;
+varying vec2 vUv;
+varying vec4 vColorAndOpacity;
+varying vec4 vPickColorAndEnabled;
+
+void main() {
+    // --- 1. 提前解包属性（GPU会自动优化，无性能损失）---
+    float show = aPositionAndShow.w;
+    float scale = aScaleAndRotationAndSizeAttenuation.x;
+    float rotation = aScaleAndRotationAndSizeAttenuation.y;
+    float sizeAttenuation = aScaleAndRotationAndSizeAttenuation.z;
+    vec2 center = aCenterAndSize.xy;
+    vec2 imageSize = aCenterAndSize.zw;
+
+    // --- 2. 输出varying变量 ---
+    vShow = show;
+    vUv = uv;
+    vColorAndOpacity = aColorAndOpacity;
+    vPickColorAndEnabled = aPickColorAndEnabled;
+
+    // --- 3. 提前隐藏不可见物体（顶点级丢弃，性能最优）---
+    if (show < 0.5 || imageSize.x <= 0.0 || imageSize.y <= 0.0) {
+        vShow = 0.0;
+        gl_Position = vec4(0.0, 0.0, 2.0, 1.0);
+        return;
+    }
+
+    // --- 4. 计算模型视图位置 ---
+    vec4 mvPosition = modelViewMatrix * vec4(aPositionAndShow.xyz, 1.0);
+
+    // --- 5. 深度检查：隐藏相机后面的物体，避免尺寸翻转 ---
+    float depth = -mvPosition.z;
+    if (depth <= 0.0) {
+        vShow = 0.0;
+        gl_Position = vec4(0.0, 0.0, 2.0, 1.0);
+        return;
+    }
+
+    // --- 6. sizeAttenuation检查：大小跟随深度
+    if (sizeAttenuation < 0.5) {
+        bool isPerspective = isPerspectiveMatrix( projectionMatrix );
+		if ( isPerspective ) scale *= depth;
+    }
+
+    // --- 7. 坐标对齐
+    float aspectRatio = imageSize.x / imageSize.y;
+    vec2 alignedPosition = ( position.xy - ( center - vec2( 0.5 ) ) ) * aspectRatio * scale;
+
+    // --- 8. 计算旋转
+	vec2 rotatedPosition;
+	rotatedPosition.x = cos( rotation ) * alignedPosition.x - sin( rotation ) * alignedPosition.y;
+	rotatedPosition.y = sin( rotation ) * alignedPosition.x + cos( rotation ) * alignedPosition.y;
+	mvPosition.xy += rotatedPosition;
+
+    // --- 9. 投影变换 ---
+    gl_Position = projectionMatrix * mvPosition;
+
+    #include <logdepthbuf_vertex>
+}
+`;
+
+const fragmentShader = `
+uniform sampler2D uTexture;
+
+#include <common>
+#include <logdepthbuf_pars_fragment>
+
+varying float vShow;
+varying vec2 vUv;
+varying vec4 vColorAndOpacity;
+varying vec4 vPickColorAndEnabled;
+
+void main() {
+    if (vShow < 0.5) {
+        discard;
+    }
+
+    float enablePickColor = vPickColorAndEnabled.w;
+
+    if (enablePickColor > 0.5){
+        gl_FragColor = vec4(vPickColorAndEnabled.xyz, 1.0);
+    } else {
+        vec4 texColor = texture2D(uTexture, vUv);
+        vec4 diffuseColor = texColor * vColorAndOpacity;
+
+        // 丢弃完全透明的像素
+        if (diffuseColor.a < 0.005) {
+            discard;
+        }
+
+        gl_FragColor = diffuseColor;
+        #include <logdepthbuf_fragment>
+        #include <tonemapping_fragment>
+	    #include <colorspace_fragment>
+    }
+}
+`;
+
+/**
+ * InstancedSprite 材质类，以attribute形式传入InstancedSprite对象实例属性
+ * 
+ * @extends ShaderMaterial
+*/
+class InstancedSpriteMaterial extends ShaderMaterial {
+    constructor() {
+        super({
+            vertexShader,
+            fragmentShader,
+            uniforms: {
+                uTexture: { value: null },
+            },
+            transparent: true,
+            depthTest: true,
+            depthWrite: true,
+        });
+    }
+    /**
+     * 图片纹理
+     * @type {Texture}
+    */
+    set texture(value) {
+        this.uniforms.uTexture.value = value;
+    }
+    get texture() {
+        return this.uniforms.uTexture.value;
+    }
+};
+
+export default InstancedSpriteMaterial;
 export { InstancedSpriteMaterial };