@lijuhong1981/three.instancedsprite 1.1.0 → 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,42 +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>
 
@@ -321,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>
@@ -371,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)
@@ -389,9 +431,20 @@ InstancedSprite实例数量
 <a name="InstancedSpriteCollection+clear"></a>
 
 ### instancedSpriteCollection.clear() ⇒ [<code>InstancedSpriteCollection</code>](#InstancedSpriteCollection)
-移除所有InstancedSprite，并清空所有Mesh的实例数据（Mesh本身保留以便复用）
+移除所有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)
@@ -415,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>
@@ -428,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>
 
@@ -454,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>
 
@@ -463,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>
@@ -475,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>
@@ -484,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)
@@ -524,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>
@@ -542,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

@@ -2,12 +2,12 @@
 
 Three.js 自带的 `Sprite` 不支持 GPU 实例化渲染。当场景中需要同时展示大量标签、图标或提示时，逐个绘制 `Sprite` 会产生大量 draw call，导致帧率明显下降。
 
-`InstancedSprite` 基于 `InstancedBufferGeometry` + 自定义 `ShaderMaterial`（或 TSL `NodeMaterial`）实现实例化渲染。**相同图片的 Sprite 会自动合并到同一个 Mesh，一次 draw call 全部绘制**，极大提升大批量标签的渲染效率。
+`InstancedSprite` 基于 `InstancedBufferGeometry` + 自定义 `ShaderMaterial`（或 TSL `NodeMaterial`）实现实例化渲染。**所有 Sprite 的图片打包进纹理图集，合并为极少数 draw call**，极大提升大批量标签的渲染效率。
 
 ## 特性
 
 - 🚀 **GPU 实例化**：基于 `InstancedBufferGeometry`，数千个 Sprite 仅需一次 draw call
-- 🏷️ **按图自动合批**：`image` 相同的 Sprite 自动归入同一个 `InstancedSpriteMesh` 统一渲染
+- 🏷️ **纹理图集合批**：不同图片打包进同一图集，一个图集（一个 Mesh）一次 draw call；图集满自动新建
 - ✏️ **属性自动同步**：直接修改 Sprite 的 `position` / `rotation` / `scale` / `color` 等属性，每帧 `update()` 时通过脏检查自动上传至 GPU，无需手动刷新
 - 🎯 **射线拾取**：内置射线检测，可直接用 `Raycaster` 拾取到具体的 `InstancedSprite` 实例
 - 🖼️ **像素级透明**：片元着色器自动丢弃完全透明的像素
@@ -32,8 +32,11 @@ import { InstancedSpriteCollection } from "@lijuhong1981/three.instancedsprite";
 const collection = new InstancedSpriteCollection();
 scene.add(collection);
 
-// 若使用 WebGPURenderer，传入 true 以启用 TSL 的 NodeMaterial
-// const collection = new InstancedSpriteCollection(true);
+// 若使用 WebGPURenderer，通过 useNodeMaterial 启用 TSL 的 NodeMaterial
+// const collection = new InstancedSpriteCollection({ useNodeMaterial: true });
+
+// 图集可配置（初始/最大边长、子图间距），默认自动扩容到 8192
+// const collection = new InstancedSpriteCollection({ maxSize: 4096 });
 
 // 每帧更新：内部做脏检查，把发生变化的属性同步到 GPU
 const onAnimate = () => {
@@ -76,16 +79,34 @@ if (intersects.length > 0) {
 }
 ```
 
+## 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；按 `image` 分组并生成对应的 `InstancedSpriteMesh` |
+| `InstancedSpriteCollection` | 继承自 `Object3D`，批量管理所有 Sprite；使用纹理图集合并 draw call |
 | `InstancedSprite` | 数据模型类，保存单个 Sprite 的全部属性；**不继承 `Object3D`**，不能直接加入 Scene，由 Collection 统一渲染 |
-| `InstancedSpriteMesh` | 继承自 `Mesh`，基于 `InstancedBufferGeometry`，同一图片的所有 Sprite 由其统一绘制 |
+| `InstancedSpriteMesh` | 继承自 `Mesh`，基于 `InstancedBufferGeometry`，一张图集对应一个 Mesh，由其统一绘制 |
 | `InstancedSpriteMaterial` | 继承自 `ShaderMaterial`，以 instanced attribute 形式接收每个 Sprite 的属性（WebGL） |
 | `InstancedSpriteNodeMaterial` | 继承自 `NodeMaterial`，基于 TSL 实现，功能与 `InstancedSpriteMaterial` 一致（WebGPU） |
 
+> 以上每个类都有对应的 `Billboard*` 别名导出（如 `BillboardCollection`、`Billboard`），语义上表示「始终面向相机的广告牌/标签」。
+
 ### InstancedSpriteCollection
 
 - `add(options)` → `InstancedSprite`：添加并返回一个 Sprite
@@ -117,7 +138,7 @@ if (intersects.length > 0) {
 
 ## 工作原理
 
-1. `InstancedSpriteCollection.add()` 创建 `InstancedSprite` 数据对象，并根据其 `image` 找到（或新建）对应的 `InstancedSpriteMesh`。
+1. `InstancedSpriteCollection.add()` 创建 `InstancedSprite` 数据对象，并将其 `image` 打包进纹理图集（同一图片只打包一次）。
 2. `InstancedSpriteMesh` 持有 `InstancedBufferGeometry`，为每个实例分配一组 instanced attribute（位置+显示、锚点+尺寸、缩放+旋转+衰减、颜色+透明度、拾取颜色）。
 3. 顶点着色器根据实例属性计算 billboard 位置（对齐、旋转、透视缩放），片元着色器采样纹理并应用颜色 / 透明度。
 4. 每帧调用 `update()`：仅当属性实际发生变化（脏检查）时才更新对应缓冲区，减少 CPU→GPU 传输开销；缓冲区按需自动扩容。

package/index.js

@@ -3,3 +3,4 @@ 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.1.0",
+  "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;