@lijuhong1981/three.instancedsprite 1.0.1 → 2.0.0

package/API.md

@@ -8,26 +8,40 @@
 <li>但它可以作为属性Module使用，修改InstancedSprite的属性会自动更新至GPU中</li>
 </ul>
 </dd>
+<dt><a href="#Billboard">Billboard</a></dt>
+<dd></dd>
 <dt><a href="#InstancedSpriteCollection">InstancedSpriteCollection</a> ⇐ <code>Object3D</code></dt>
 <dd><p>InstancedSpriteCollection类，批量管理InstancedSprite实例</p>
 <ul>
 <li>继承自Object3D</li>
-<li>根据InstancedSprite的图像属性生成InstancedSpriteMaterial和InstancedSpriteMesh，</li>
-<li>管理InstancedSprite与InstancedSpriteMesh实例</li>
+<li>使用纹理图集将不同图片打包，一张图集对应一个 InstancedSpriteMesh（一次 draw call）</li>
+<li>图集扩容到上限后会新建图集与 Mesh</li>
 </ul>
 </dd>
+<dt><a href="#BillboardCollection">BillboardCollection</a></dt>
+<dd></dd>
 <dt><a href="#InstancedSpriteMaterial">InstancedSpriteMaterial</a> ⇐ <code>ShaderMaterial</code></dt>
 <dd><p>InstancedSprite 材质类，以attribute形式传入InstancedSprite对象实例属性</p>
 </dd>
+<dt><a href="#BillboardMaterial">BillboardMaterial</a></dt>
+<dd></dd>
 <dt><a href="#InstancedSpriteMesh">InstancedSpriteMesh</a> ⇐ <code>Mesh</code></dt>
 <dd><p>InstancedSpriteMesh类，基于InstancedBufferGeometry实现的高性能InstancedSprite渲染组件</p>
+<p>一张图集纹理对应一个 InstancedSpriteMesh，所有使用该图集的 Sprite 由其统一绘制</p>
 </dd>
+<dt><a href="#BillboardMesh">BillboardMesh</a></dt>
+<dd></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>
+<dt><a href="#BillboardNodeMaterial">BillboardNodeMaterial</a></dt>
+<dd></dd>
+<dt><a href="#TextureAtlas">TextureAtlas</a></dt>
+<dd><p>纹理图集，将多张图片按行（shelf）打包进一张 Canvas 纹理，用于合并 draw call</p>
+</dd>
 </dl>
 
 ## Constants
@@ -257,41 +271,58 @@ Computes intersection points between a casted ray and this sprite.
 | intersects | <code>Array.&lt;Object&gt;</code> | The target array that holds the intersection points. |
 | modelViewMatrix | <code>Matrix4</code> |  |
 
+<a name="Billboard"></a>
+
+## Billboard
+**Kind**: global class  
+<a name="new_Billboard_new"></a>
+
+### new Billboard()
+InstancedSprite 的别名（广告牌语义）。
+
 <a name="InstancedSpriteCollection"></a>
 
 ## InstancedSpriteCollection ⇐ <code>Object3D</code>
 InstancedSpriteCollection类，批量管理InstancedSprite实例
 
 * 继承自Object3D
-* 根据InstancedSprite的图像属性生成InstancedSpriteMaterial和InstancedSpriteMesh，
-* 管理InstancedSprite与InstancedSpriteMesh实例
+* 使用纹理图集将不同图片打包，一张图集对应一个 InstancedSpriteMesh（一次 draw call）
+* 图集扩容到上限后会新建图集与 Mesh
 
 **Kind**: global class  
 **Extends**: <code>Object3D</code>  
 
 * [InstancedSpriteCollection](#InstancedSpriteCollection) ⇐ <code>Object3D</code>
-    * [new InstancedSpriteCollection([useNodeMaterial])](#new_InstancedSpriteCollection_new)
+    * [new InstancedSpriteCollection([options])](#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>
+    * [.depthWrite](#InstancedSpriteCollection+depthWrite) : <code>boolean</code>
     * [.instancedSprites](#InstancedSpriteCollection+instancedSprites) : [<code>Array.&lt;InstancedSprite&gt;</code>](#InstancedSprite)
     * [.size](#InstancedSpriteCollection+size) : <code>number</code>
     * [._setImage(source, sprite)](#InstancedSpriteCollection+_setImage)
     * [.get(index)](#InstancedSpriteCollection+get) ⇒ [<code>InstancedSprite</code>](#InstancedSprite) \| <code>undefined</code>
     * [.getByUuid(uuid)](#InstancedSpriteCollection+getByUuid) ⇒ [<code>InstancedSprite</code>](#InstancedSprite) \| <code>undefined</code>
-    * [.add()](#InstancedSpriteCollection+add) ⇒ [<code>InstancedSprite</code>](#InstancedSprite)
+    * [.add(options)](#InstancedSpriteCollection+add) ⇒ [<code>InstancedSprite</code>](#InstancedSprite)
     * [.remove(sprite)](#InstancedSpriteCollection+remove) ⇒ [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)
+    * [.clear()](#InstancedSpriteCollection+clear) ⇒ [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)
+    * [.reserve(capacity)](#InstancedSpriteCollection+reserve) ⇒ [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)
     * [.forEach(callback)](#InstancedSpriteCollection+forEach) ⇒ [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)
     * [.raycast(raycaster, intersects)](#InstancedSpriteCollection+raycast)
+    * [.dispose()](#InstancedSpriteCollection+dispose) ⇒ [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)
 
 <a name="new_InstancedSpriteCollection_new"></a>
 
-### new InstancedSpriteCollection([useNodeMaterial])
+### new InstancedSpriteCollection([options])
 
 | Param | Type | Default | Description |
 | --- | --- | --- | --- |
-| [useNodeMaterial] | <code>boolean</code> | <code>false</code> | 是否使用TSL的NodeMaterial，默认false |
+| [options] | <code>object</code> |  | 配置项 |
+| [options.useNodeMaterial] | <code>boolean</code> | <code>false</code> | 是否使用TSL的NodeMaterial（WebGPU），默认false |
+| [options.initialSize] | <code>number</code> | <code>1024</code> | 图集初始边长 |
+| [options.maxSize] | <code>number</code> | <code>8192</code> | 图集最大边长 |
+| [options.padding] | <code>number</code> | <code>2</code> | 子图间距 |
 
 <a name="InstancedSpriteCollection+useNodeMaterial"></a>
 
@@ -320,6 +351,13 @@ InstancedSpriteCollection对象标识
 ### instancedSpriteCollection.depthTest : <code>boolean</code>
 深度测试开关，默认为true，开启后会进行深度测试以正确处理遮挡关系，但可能会有性能影响；如果关闭则所有InstancedSprite都会被渲染在最前面，适合需要始终显示的UI元素等场景
 
+**Kind**: instance property of [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)  
+**Default**: <code>true</code>  
+<a name="InstancedSpriteCollection+depthWrite"></a>
+
+### instancedSpriteCollection.depthWrite : <code>boolean</code>
+深度写入开关，默认为true；多个半透明 Sprite 重叠时，开启深度写入可能导致排序瑕疵（后方 Sprite 被错误遮挡），关闭可缓解，适合半透明标签/粒子等场景
+
 **Kind**: instance property of [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)  
 **Default**: <code>true</code>  
 <a name="InstancedSpriteCollection+instancedSprites"></a>
@@ -370,10 +408,15 @@ InstancedSprite实例数量
 
 <a name="InstancedSpriteCollection+add"></a>
 
-### instancedSpriteCollection.add() ⇒ [<code>InstancedSprite</code>](#InstancedSprite)
+### instancedSpriteCollection.add(options) ⇒ [<code>InstancedSprite</code>](#InstancedSprite)
 添加InstancedSprite
 
 **Kind**: instance method of [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| options | [<code>InstancedSpriteOptions</code>](#InstancedSpriteOptions) | 初始化配置项 |
+
 <a name="InstancedSpriteCollection+remove"></a>
 
 ### instancedSpriteCollection.remove(sprite) ⇒ [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)
@@ -385,6 +428,23 @@ 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+reserve"></a>
+
+### instancedSpriteCollection.reserve(capacity) ⇒ [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)
+预分配所有Mesh的容量，避免后续动态扩容
+
+**Kind**: instance method of [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| capacity | <code>number</code> | 需要预留的实例数量 |
+
 <a name="InstancedSpriteCollection+forEach"></a>
 
 ### instancedSpriteCollection.forEach(callback) ⇒ [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)
@@ -408,6 +468,21 @@ 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="InstancedSpriteCollection+dispose"></a>
+
+### instancedSpriteCollection.dispose() ⇒ [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)
+释放所有 GPU 资源（几何体、材质、图集纹理），并移除所有子 Mesh
+
+**Kind**: instance method of [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)  
+<a name="BillboardCollection"></a>
+
+## BillboardCollection
+**Kind**: global class  
+<a name="new_BillboardCollection_new"></a>
+
+### new BillboardCollection()
+InstancedSpriteCollection 的别名。
+
 <a name="InstancedSpriteMaterial"></a>
 
 ## InstancedSpriteMaterial ⇐ <code>ShaderMaterial</code>
@@ -421,24 +496,39 @@ InstancedSprite 材质类，以attribute形式传入InstancedSprite对象实例
 图片纹理
 
 **Kind**: instance property of [<code>InstancedSpriteMaterial</code>](#InstancedSpriteMaterial)  
+<a name="BillboardMaterial"></a>
+
+## BillboardMaterial
+**Kind**: global class  
+<a name="new_BillboardMaterial_new"></a>
+
+### new BillboardMaterial()
+InstancedSpriteMaterial 的别名。
+
 <a name="InstancedSpriteMesh"></a>
 
 ## InstancedSpriteMesh ⇐ <code>Mesh</code>
 InstancedSpriteMesh类，基于InstancedBufferGeometry实现的高性能InstancedSprite渲染组件
 
+一张图集纹理对应一个 InstancedSpriteMesh，所有使用该图集的 Sprite 由其统一绘制
+
 **Kind**: global class  
 **Extends**: <code>Mesh</code>  
 
 * [InstancedSpriteMesh](#InstancedSpriteMesh) ⇐ <code>Mesh</code>
     * [new InstancedSpriteMesh(collection, texture)](#new_InstancedSpriteMesh_new)
     * [.type](#InstancedSpriteMesh+type) : <code>string</code>
+    * [.frustumCulled](#InstancedSpriteMesh+frustumCulled) : <code>boolean</code>
     * [.isInstancedSpriteMesh](#InstancedSpriteMesh+isInstancedSpriteMesh) : <code>boolean</code>
     * [.depthTest](#InstancedSpriteMesh+depthTest) : <code>boolean</code>
+    * [.depthWrite](#InstancedSpriteMesh+depthWrite) : <code>boolean</code>
     * [.instancedSprites](#InstancedSpriteMesh+instancedSprites) : [<code>Array.&lt;InstancedSprite&gt;</code>](#InstancedSprite)
+    * [.reserve(capacity)](#InstancedSpriteMesh+reserve) ⇒ [<code>InstancedSpriteMesh</code>](#InstancedSpriteMesh)
     * [.add(sprite)](#InstancedSpriteMesh+add) ⇒ [<code>InstancedSpriteMesh</code>](#InstancedSpriteMesh)
     * [.remove(sprite)](#InstancedSpriteMesh+remove) ⇒ [<code>InstancedSpriteMesh</code>](#InstancedSpriteMesh)
     * [.clear()](#InstancedSpriteMesh+clear) ⇒ [<code>InstancedSpriteMesh</code>](#InstancedSpriteMesh)
     * [.raycast(raycaster, intersects)](#InstancedSpriteMesh+raycast)
+    * [.dispose()](#InstancedSpriteMesh+dispose)
 
 <a name="new_InstancedSpriteMesh_new"></a>
 
@@ -447,7 +537,7 @@ InstancedSpriteMesh类，基于InstancedBufferGeometry实现的高性能Instance
 | Param | Type | Description |
 | --- | --- | --- |
 | collection | [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection) | 所属的InstancedSpriteCollection实例，必填 |
-| texture | <code>Texture</code> | 材质图像纹理，必填 |
+| texture | <code>Texture</code> | 图集纹理，必填 |
 
 <a name="InstancedSpriteMesh+type"></a>
 
@@ -456,6 +546,13 @@ InstancedSpriteMesh类，基于InstancedBufferGeometry实现的高性能Instance
 
 **Kind**: instance property of [<code>InstancedSpriteMesh</code>](#InstancedSpriteMesh)  
 **Read only**: true  
+<a name="InstancedSpriteMesh+frustumCulled"></a>
+
+### instancedSpriteMesh.frustumCulled : <code>boolean</code>
+实例化几何体的包围球基于单位四边形（位于原点），不包含实例位置，视锥剔除会把远离原点的实例整批误剔除，因此禁用
+
+**Kind**: instance property of [<code>InstancedSpriteMesh</code>](#InstancedSpriteMesh)  
+**Default**: <code>false</code>  
 <a name="InstancedSpriteMesh+isInstancedSpriteMesh"></a>
 
 ### instancedSpriteMesh.isInstancedSpriteMesh : <code>boolean</code>
@@ -468,6 +565,13 @@ InstancedSpriteMesh对象标识
 ### instancedSpriteMesh.depthTest : <code>boolean</code>
 深度测试开关，默认为true，开启后会进行深度测试以正确处理遮挡关系，但可能会有性能影响；如果关闭则所有InstancedSprite都会被渲染在最前面，适合需要始终显示的UI元素等场景
 
+**Kind**: instance property of [<code>InstancedSpriteMesh</code>](#InstancedSpriteMesh)  
+**Default**: <code>true</code>  
+<a name="InstancedSpriteMesh+depthWrite"></a>
+
+### instancedSpriteMesh.depthWrite : <code>boolean</code>
+深度写入开关，默认为true；多个半透明 Sprite 重叠时，开启深度写入可能导致排序瑕疵（后方 Sprite 被错误遮挡），关闭可缓解，适合半透明标签/粒子等场景
+
 **Kind**: instance property of [<code>InstancedSpriteMesh</code>](#InstancedSpriteMesh)  
 **Default**: <code>true</code>  
 <a name="InstancedSpriteMesh+instancedSprites"></a>
@@ -477,6 +581,17 @@ InstancedSprite对象数组
 
 **Kind**: instance property of [<code>InstancedSpriteMesh</code>](#InstancedSpriteMesh)  
 **Read only**: true  
+<a name="InstancedSpriteMesh+reserve"></a>
+
+### instancedSpriteMesh.reserve(capacity) ⇒ [<code>InstancedSpriteMesh</code>](#InstancedSpriteMesh)
+预分配容量，避免后续动态扩容（不改变当前实际绘制的实例数量）
+
+**Kind**: instance method of [<code>InstancedSpriteMesh</code>](#InstancedSpriteMesh)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| capacity | <code>number</code> | 需要预留的实例数量 |
+
 <a name="InstancedSpriteMesh+add"></a>
 
 ### instancedSpriteMesh.add(sprite) ⇒ [<code>InstancedSpriteMesh</code>](#InstancedSpriteMesh)
@@ -517,6 +632,21 @@ 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="InstancedSpriteMesh+dispose"></a>
+
+### instancedSpriteMesh.dispose()
+释放 GPU 资源
+
+**Kind**: instance method of [<code>InstancedSpriteMesh</code>](#InstancedSpriteMesh)  
+<a name="BillboardMesh"></a>
+
+## BillboardMesh
+**Kind**: global class  
+<a name="new_BillboardMesh_new"></a>
+
+### new BillboardMesh()
+InstancedSpriteMesh 的别名。
+
 <a name="InstancedSpriteNodeMaterial"></a>
 
 ## InstancedSpriteNodeMaterial ⇐ <code>NodeMaterial</code>
@@ -535,6 +665,79 @@ InstancedSpriteNodeMaterial 材质类，基于 Three.js TSL (Three Shading Langu
 图片纹理
 
 **Kind**: instance property of [<code>InstancedSpriteNodeMaterial</code>](#InstancedSpriteNodeMaterial)  
+<a name="BillboardNodeMaterial"></a>
+
+## BillboardNodeMaterial
+**Kind**: global class  
+<a name="new_BillboardNodeMaterial_new"></a>
+
+### new BillboardNodeMaterial()
+InstancedSpriteNodeMaterial 的别名。
+
+<a name="TextureAtlas"></a>
+
+## TextureAtlas
+纹理图集，将多张图片按行（shelf）打包进一张 Canvas 纹理，用于合并 draw call
+
+**Kind**: global class  
+
+* [TextureAtlas](#TextureAtlas)
+    * [new TextureAtlas([options])](#new_TextureAtlas_new)
+    * [.add(source)](#TextureAtlas+add) ⇒ <code>Object</code> \| <code>null</code>
+    * [.getRect(source)](#TextureAtlas+getRect) ⇒ <code>Object</code> \| <code>undefined</code>
+    * [.grow()](#TextureAtlas+grow) ⇒ <code>boolean</code>
+    * [.getUvRect(rect)](#TextureAtlas+getUvRect) ⇒ <code>Array.&lt;number&gt;</code>
+
+<a name="new_TextureAtlas_new"></a>
+
+### new TextureAtlas([options])
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| [options] | <code>object</code> |  |  |
+| [options.initialSize] | <code>number</code> | <code>1024</code> | 初始边长（正方形，单位像素） |
+| [options.maxSize] | <code>number</code> | <code>8192</code> | 最大边长，自动扩容到该值后不再增大 |
+| [options.padding] | <code>number</code> | <code>2</code> | 子图间距，防止线性过滤时边缘渗色 |
+
+<a name="TextureAtlas+add"></a>
+
+### textureAtlas.add(source) ⇒ <code>Object</code> \| <code>null</code>
+将图片加入图集，返回其像素矩形；已加入过则返回缓存；图集整体已满则返回null
+
+**Kind**: instance method of [<code>TextureAtlas</code>](#TextureAtlas)  
+
+| Param | Type |
+| --- | --- |
+| source | <code>HTMLImageElement</code> \| <code>HTMLCanvasElement</code> | 
+
+<a name="TextureAtlas+getRect"></a>
+
+### textureAtlas.getRect(source) ⇒ <code>Object</code> \| <code>undefined</code>
+获取图片已分配的像素矩形
+
+**Kind**: instance method of [<code>TextureAtlas</code>](#TextureAtlas)  
+
+| Param | Type |
+| --- | --- |
+| source | <code>HTMLImageElement</code> \| <code>HTMLCanvasElement</code> | 
+
+<a name="TextureAtlas+grow"></a>
+
+### textureAtlas.grow() ⇒ <code>boolean</code>
+扩容图集（边长翻倍），成功返回true；已达最大尺寸返回false
+
+**Kind**: instance method of [<code>TextureAtlas</code>](#TextureAtlas)  
+<a name="TextureAtlas+getUvRect"></a>
+
+### textureAtlas.getUvRect(rect) ⇒ <code>Array.&lt;number&gt;</code>
+将像素矩形转为归一化 UV（uOffset, vOffset, uScale, vScale）
+
+**Kind**: instance method of [<code>TextureAtlas</code>](#TextureAtlas)  
+
+| Param | Type |
+| --- | --- |
+| rect | <code>Object</code> | 
+
 <a name="imageLoader"></a>
 
 ## imageLoader

package/README.md

@@ -1,55 +1,146 @@
-# 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 的图片打包进纹理图集，合并为极少数 draw call**，极大提升大批量标签的渲染效率。
+
+## 特性
+
+- 🚀 **GPU 实例化**：基于 `InstancedBufferGeometry`，数千个 Sprite 仅需一次 draw call
+- 🏷️ **纹理图集合批**：不同图片打包进同一图集，一个图集（一个 Mesh）一次 draw call；图集满自动新建
+- ✏️ **属性自动同步**：直接修改 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，通过 useNodeMaterial 启用 TSL 的 NodeMaterial
+// const collection = new InstancedSpriteCollection({ useNodeMaterial: true });
+
+// 图集可配置（初始/最大边长、子图间距），默认自动扩容到 8192
+// const collection = new InstancedSpriteCollection({ maxSize: 4096 });
+
+// 每帧更新：内部做脏检查，把发生变化的属性同步到 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; // 实例索引
+}
+```
+
+## Billboard 别名
+
+所有 `InstancedSprite*` 类都有对应的 `Billboard*` 别名导出，语义上表示「始终面向相机的广告牌/标签」，用法完全一致：
+
+```js
+import { BillboardCollection, Billboard } from "@lijuhong1981/three.instancedsprite";
+
+// BillboardCollection === InstancedSpriteCollection
+const collection = new BillboardCollection();
+scene.add(collection);
+
+// Billboard === InstancedSprite
+const billboard = collection.add({ image: './res/icon.png', position: [0, 0, 0] });
+console.log(billboard instanceof Billboard); // true
+```
+
+## 主要 API
+
+| 类 | 说明 |
+| --- | --- |
+| `InstancedSpriteCollection` | 继承自 `Object3D`，批量管理所有 Sprite；使用纹理图集合并 draw call |
+| `InstancedSprite` | 数据模型类，保存单个 Sprite 的全部属性；**不继承 `Object3D`**，不能直接加入 Scene，由 Collection 统一渲染 |
+| `InstancedSpriteMesh` | 继承自 `Mesh`，基于 `InstancedBufferGeometry`，一张图集对应一个 Mesh，由其统一绘制 |
+| `InstancedSpriteMaterial` | 继承自 `ShaderMaterial`，以 instanced attribute 形式接收每个 Sprite 的属性（WebGL） |
+| `InstancedSpriteNodeMaterial` | 继承自 `NodeMaterial`，基于 TSL 实现，功能与 `InstancedSpriteMaterial` 一致（WebGPU） |
+
+> 以上每个类都有对应的 `Billboard*` 别名导出（如 `BillboardCollection`、`Billboard`），语义上表示「始终面向相机的广告牌/标签」。
+
+### 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` 打包进纹理图集（同一图片只打包一次）。
+2. `InstancedSpriteMesh` 持有 `InstancedBufferGeometry`，为每个实例分配一组 instanced attribute（位置+显示、锚点+尺寸、缩放+旋转+衰减、颜色+透明度、拾取颜色）。
+3. 顶点着色器根据实例属性计算 billboard 位置（对齐、旋转、透视缩放），片元着色器采样纹理并应用颜色 / 透明度。
+4. 每帧调用 `update()`：仅当属性实际发生变化（脏检查）时才更新对应缓冲区，减少 CPU→GPU 传输开销；缓冲区按需自动扩容。
+
+## [API 文档](./API.md)

package/index.js

@@ -1,5 +1,6 @@
-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";
+export * from "./src/TextureAtlas.js";

package/package.json

@@ -1,16 +1,22 @@
 {
   "name": "@lijuhong1981/three.instancedsprite",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "description": "",
   "type": "module",
   "module": "index.js",
   "main": "index.js",
+  "files": [
+    "index.js",
+    "src/",
+    "API.md"
+  ],
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
-    "docs": "jsdoc2md --files src/*.js > API.md"
+    "docs": "jsdoc2md --files src/*.js > API.md",
+    "dev": "vite test"
   },
   "repository": {
     "type": "git",
@@ -36,6 +42,7 @@
     "three": ">=0.171.0"
   },
   "devDependencies": {
-    "jsdoc-to-markdown": "^9.1.3"
+    "jsdoc-to-markdown": "^9.1.3",
+    "vite": "^8.3.3"
   }
-}
+}

package/src/InstancedSprite.js

@@ -2,7 +2,7 @@ import Check from "@lijuhong1981/jscheck/src/Check.js";
 import ImageLoader from "@lijuhong1981/jsload/src/ImageLoader.js";
 import { Loader } from "@lijuhong1981/jsload/src/Loader.js";
 import setValues from "@lijuhong1981/three.utils/src/setValues.js";
-import { Color, InstancedBufferGeometry, MathUtils, Matrix4, Triangle, Vector2, Vector3 } from "three";
+import { Color, InstancedBufferGeometry, MathUtils, Matrix4, Triangle, Vector2, Vector3, Vector4 } from "three";
 
 /**
  * @import InstancedSpriteCollection from "./InstancedSpriteCollection.js";
@@ -169,6 +169,13 @@ class InstancedSprite {
         */
         this.imageSize = new Vector2(0, 0);
         this._imageSize = new Vector2(0, 0);
+        /**
+         * 图集UV区域（x: u偏移, y: v偏移, z: u缩放, w: v缩放），非图集模式默认为(0,0,1,1)即整张纹理
+         * @type {Vector4}
+         * @ignore
+        */
+        this.uvRect = new Vector4(0, 0, 1, 1);
+        this._uvRect = new Vector4(0, 0, 1, 1);
         this._image = null;
         /**
          * 拾取颜色，用于GPU拾取，由Picking管理器设置和使用，用户无需关心
@@ -366,3 +373,9 @@ class InstancedSprite {
 
 export default InstancedSprite;
 export { InstancedSprite };
+/**
+ * InstancedSprite 的别名（广告牌语义）。
+ * @class
+ * @name Billboard
+ */
+export const Billboard = InstancedSprite;