@lijuhong1981/three.instancedsprite 1.0.0 → 1.1.0

package/.gitattributes

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

package/API.md

@@ -22,6 +22,12 @@
 <dt><a href="#InstancedSpriteMesh">InstancedSpriteMesh</a> ⇐ <code>Mesh</code></dt>
 <dd><p>InstancedSpriteMesh类，基于InstancedBufferGeometry实现的高性能InstancedSprite渲染组件</p>
 </dd>
+<dt><a href="#InstancedSpriteNodeMaterial">InstancedSpriteNodeMaterial</a> ⇐ <code>NodeMaterial</code></dt>
+<dd><p>InstancedSpriteNodeMaterial 材质类，基于 Three.js TSL (Three Shading Language) 语法实现</p>
+<p>功能与 InstancedSpriteMaterial (ShaderMaterial) 完全相同，但使用 TSL 节点系统构建，
+可更好地与 Three.js 的 NodeMaterial 管线集成（自动处理色调映射、色彩空间转换等）。</p>
+<p><strong>注意</strong>：使用此类需要 Three.js 的 WebGPU/TSL 构建（<code>three/webgpu</code>），非标准 <code>three</code> 构建。</p>
+</dd>
 </dl>
 
 ## Constants
@@ -62,6 +68,7 @@ InstancedSprite 数据模型类，用于存储单个 InstancedSprite 的所有
     * [.color](#InstancedSprite+color) : <code>Color</code>
     * [.opacity](#InstancedSprite+opacity) : <code>number</code>
     * [.imageSize](#InstancedSprite+imageSize) : <code>Vector2</code>
+    * [.userData](#InstancedSprite+userData) : <code>object</code>
     * [.isInstancedSprite](#InstancedSprite+isInstancedSprite) : <code>boolean</code>
     * [.visible](#InstancedSprite+visible) : <code>boolean</code>
     * [.rotationDegrees](#InstancedSprite+rotationDegrees) : <code>number</code>
@@ -70,7 +77,7 @@ InstancedSprite 数据模型类，用于存储单个 InstancedSprite 的所有
     * [.imageWidth](#InstancedSprite+imageWidth) : <code>number</code>
     * [.imageHeight](#InstancedSprite+imageHeight) : <code>number</code>
     * [.geometry](#InstancedSprite+geometry) : <code>InstancedBufferGeometry</code>
-    * [.material](#InstancedSprite+material) : [<code>InstancedSpriteMaterial</code>](#InstancedSpriteMaterial)
+    * [.material](#InstancedSprite+material) : [<code>InstancedSpriteMaterial</code>](#InstancedSpriteMaterial) \| [<code>InstancedSpriteNodeMaterial</code>](#InstancedSpriteNodeMaterial)
     * [.setValues(options)](#InstancedSprite+setValues) ⇒ [<code>InstancedSprite</code>](#InstancedSprite)
     * [.remove()](#InstancedSprite+remove) ⇒ [<code>InstancedSprite</code>](#InstancedSprite)
     * [.raycast(raycaster, intersects, modelViewMatrix)](#InstancedSprite+raycast)
@@ -151,6 +158,13 @@ InstancedSprite 数据模型类，用于存储单个 InstancedSprite 的所有
 ### instancedSprite.imageSize : <code>Vector2</code>
 图片尺寸（像素），图片加载完成后可用
 
+**Kind**: instance property of [<code>InstancedSprite</code>](#InstancedSprite)  
+**Read only**: true  
+<a name="InstancedSprite+userData"></a>
+
+### instancedSprite.userData : <code>object</code>
+用户自定义数据存储对象，InstancedSprite本身不使用该属性，用户可以自由使用它来存储任意数据
+
 **Kind**: instance property of [<code>InstancedSprite</code>](#InstancedSprite)  
 **Read only**: true  
 <a name="InstancedSprite+isInstancedSprite"></a>
@@ -208,8 +222,8 @@ InstancedSprite对象的几何体属性
 **Read only**: true  
 <a name="InstancedSprite+material"></a>
 
-### instancedSprite.material : [<code>InstancedSpriteMaterial</code>](#InstancedSpriteMaterial)
-InstancedSprite对象的材质属性
+### instancedSprite.material : [<code>InstancedSpriteMaterial</code>](#InstancedSpriteMaterial) \| [<code>InstancedSpriteNodeMaterial</code>](#InstancedSpriteNodeMaterial)
+InstancedSprite对象的材质属性，可能是InstancedSpriteMaterial或InstancedSpriteNodeMaterial
 
 **Kind**: instance property of [<code>InstancedSprite</code>](#InstancedSprite)  
 **Read only**: true  
@@ -256,6 +270,8 @@ InstancedSpriteCollection类，批量管理InstancedSprite实例
 **Extends**: <code>Object3D</code>  
 
 * [InstancedSpriteCollection](#InstancedSpriteCollection) ⇐ <code>Object3D</code>
+    * [new InstancedSpriteCollection([useNodeMaterial])](#new_InstancedSpriteCollection_new)
+    * [.useNodeMaterial](#InstancedSpriteCollection+useNodeMaterial) : <code>boolean</code>
     * [.type](#InstancedSpriteCollection+type) : <code>string</code>
     * [.isInstancedSpriteCollection](#InstancedSpriteCollection+isInstancedSpriteCollection) : <code>boolean</code>
     * [.depthTest](#InstancedSpriteCollection+depthTest) : <code>boolean</code>
@@ -266,9 +282,26 @@ 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)
 
+<a name="new_InstancedSpriteCollection_new"></a>
+
+### new InstancedSpriteCollection([useNodeMaterial])
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| [useNodeMaterial] | <code>boolean</code> | <code>false</code> | 是否使用TSL的NodeMaterial，默认false |
+
+<a name="InstancedSpriteCollection+useNodeMaterial"></a>
+
+### instancedSpriteCollection.useNodeMaterial : <code>boolean</code>
+是否使用TSL的NodeMaterial，默认false
+
+**Kind**: instance property of [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)  
+**Default**: <code>false</code>  
+**Read only**: true  
 <a name="InstancedSpriteCollection+type"></a>
 
 ### instancedSpriteCollection.type : <code>string</code>
@@ -353,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)
@@ -485,6 +524,24 @@ Computes intersection points between a casted ray and this sprite.
 | raycaster | <code>Raycaster</code> | The raycaster. |
 | intersects | <code>Array.&lt;Object&gt;</code> | The target array that holds the intersection points. |
 
+<a name="InstancedSpriteNodeMaterial"></a>
+
+## InstancedSpriteNodeMaterial ⇐ <code>NodeMaterial</code>
+InstancedSpriteNodeMaterial 材质类，基于 Three.js TSL (Three Shading Language) 语法实现
+
+功能与 InstancedSpriteMaterial (ShaderMaterial) 完全相同，但使用 TSL 节点系统构建，
+可更好地与 Three.js 的 NodeMaterial 管线集成（自动处理色调映射、色彩空间转换等）。
+
+**注意**：使用此类需要 Three.js 的 WebGPU/TSL 构建（`three/webgpu`），非标准 `three` 构建。
+
+**Kind**: global class  
+**Extends**: <code>NodeMaterial</code>  
+<a name="InstancedSpriteNodeMaterial+texture"></a>
+
+### instancedSpriteNodeMaterial.texture : <code>Texture</code> \| <code>null</code>
+图片纹理
+
+**Kind**: instance property of [<code>InstancedSpriteNodeMaterial</code>](#InstancedSpriteNodeMaterial)  
 <a name="imageLoader"></a>
 
 ## imageLoader
@@ -492,6 +549,7 @@ Computes intersection points between a casted ray and this sprite.
 **Import**: InstancedSpriteCollection from "./InstancedSpriteCollection.js";  
 **Import**: InstancedSpriteMesh from "./InstancedSpriteMesh.js";  
 **Import**: InstancedSpriteMaterial from "./InstancedSpriteMaterial.js";  
+**Import**: InstancedSpriteNodeMaterial from "./InstancedSpriteNodeMaterial.js";  
 <a name="InstancedSpriteOptions"></a>
 
 ## InstancedSpriteOptions : <code>object</code>

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.0",
+  "version": "1.1.0",
   "description": "",
   "type": "module",
   "module": "index.js",

package/src/InstancedSprite.js

@@ -8,6 +8,7 @@ import { Color, InstancedBufferGeometry, MathUtils, Matrix4, Triangle, Vector2,
  * @import InstancedSpriteCollection from "./InstancedSpriteCollection.js";
  * @import InstancedSpriteMesh from "./InstancedSpriteMesh.js";
  * @import InstancedSpriteMaterial from "./InstancedSpriteMaterial.js";
+ * @import InstancedSpriteNodeMaterial from "./InstancedSpriteNodeMaterial.js";
  */
 
 const imageLoader = new ImageLoader({ cacheType: Loader.CacheType.ALONE, });
@@ -169,6 +170,28 @@ class InstancedSprite {
         this.imageSize = new Vector2(0, 0);
         this._imageSize = new Vector2(0, 0);
         this._image = null;
+        /**
+         * 拾取颜色，用于GPU拾取，由Picking管理器设置和使用，用户无需关心
+         * @type {Color}
+         * @readonly
+         * @private
+        */
+        this.pickColor = new Color();
+        this._pickColor = new Color();
+        /**
+         * 是否启用拾取颜色，用于GPU拾取，由Picking管理器设置和使用，用户无需关心
+         * @type {boolean}
+         * @readonly
+         * @private
+        */
+        this.enablePickColor = false;
+        this._enablePickColor = false;
+        /**
+         * 用户自定义数据存储对象，InstancedSprite本身不使用该属性，用户可以自由使用它来存储任意数据
+         * @type {object}
+         * @readonly
+        */
+        this.userData = {};
 
         this.setValues(options);
     }
@@ -249,8 +272,8 @@ class InstancedSprite {
         return this._mesh ? this._mesh.geometry : undefined;
     }
     /**
-     * InstancedSprite对象的材质属性
-     * @type {InstancedSpriteMaterial}
+     * InstancedSprite对象的材质属性，可能是InstancedSpriteMaterial或InstancedSpriteNodeMaterial
+     * @type {InstancedSpriteMaterial|InstancedSpriteNodeMaterial}
      * @readonly
     */
     get material() {

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