@lijuhong1981/three.instancedsprite 1.0.0 → 1.0.1

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>
@@ -269,6 +285,22 @@ InstancedSpriteCollection类，批量管理InstancedSprite实例
     * [.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>
@@ -485,6 +517,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 +542,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lijuhong1981/three.instancedsprite",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "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/InstancedSpriteMaterial.js

@@ -13,10 +13,12 @@ attribute vec4 aPositionAndShow; // xyz: InstancedSprite位置（世界空间）
 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会自动优化，无性能损失）---
@@ -31,6 +33,7 @@ void main() {
     vShow = show;
     vUv = uv;
     vColorAndOpacity = aColorAndOpacity;
+    vPickColorAndEnabled = aPickColorAndEnabled;
 
     // --- 3. 提前隐藏不可见物体（顶点级丢弃，性能最优）---
     if (show < 0.5 || imageSize.x <= 0.0 || imageSize.y <= 0.0) {
@@ -82,21 +85,31 @@ uniform sampler2D uTexture;
 varying float vShow;
 varying vec2 vUv;
 varying vec4 vColorAndOpacity;
+varying vec4 vPickColorAndEnabled;
 
 void main() {
-    vec4 texColor = texture2D(uTexture, vUv);
-    vec4 diffuseColor = texColor * vColorAndOpacity;
-
-    // 丢弃完全透明的像素
-    if (diffuseColor.a < 0.005 || vShow < 0.5) {
+    if (vShow < 0.5) {
         discard;
     }
 
-    gl_FragColor = diffuseColor;
+    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;
 
-    #include <logdepthbuf_fragment>
-    #include <tonemapping_fragment>
-	#include <colorspace_fragment>
+        // 丢弃完全透明的像素
+        if (diffuseColor.a < 0.005) {
+            discard;
+        }
+
+        gl_FragColor = diffuseColor;
+        #include <logdepthbuf_fragment>
+        #include <tonemapping_fragment>
+	    #include <colorspace_fragment>
+    }
 }
 `;
 

package/src/InstancedSpriteMesh.js

@@ -36,6 +36,7 @@ const aPositionAndShow = 'aPositionAndShow';
 const aCenterAndSize = 'aCenterAndSize';
 const aScaleAndRotationAndSizeAttenuation = 'aScaleAndRotationAndSizeAttenuation';
 const aColorAndOpacity = 'aColorAndOpacity';
+const aPickColorAndEnabled = 'aPickColorAndEnabled';
 /**
  * InstancedSpriteMaterial使用的attribute名称常量与itemSize大小，InstancedSpriteMesh会根据名称和itemSize创建InstancedBufferAttribute
  * @type {Object<string, number>}
@@ -47,6 +48,7 @@ const AttributesItemSize = Object.freeze({
     aCenterAndSize: 4,
     aScaleAndRotationAndSizeAttenuation: 3,
     aColorAndOpacity: 4,
+    aPickColorAndEnabled: 4,
 });
 /**
  * 检查并更新一个InstancedSprite实例的数据到对应的InstancedBufferAttribute位置
@@ -67,6 +69,8 @@ function checkAndUpdateInstancedSprite(mesh, sprite) {
     const sizeAttenuationChanged = (sprite._sizeAttenuation !== sprite.sizeAttenuation);
     const colorChanged = (sprite._color.equals(sprite.color) === false);
     const opacityChanged = (sprite._opacity !== sprite.opacity);
+    const pickColorChanged = (sprite._pickColor.equals(sprite.pickColor) === false);
+    const enablePickColorChanged = (sprite._enablePickColor !== sprite.enablePickColor);
 
     let idx = 0;
 
@@ -131,6 +135,21 @@ function checkAndUpdateInstancedSprite(mesh, sprite) {
         }
         mesh.geometry.attributes.aColorAndOpacity.needsUpdate = true;
     }
+
+    if (pickColorChanged || enablePickColorChanged) {
+        idx = index * AttributesItemSize.aPickColorAndEnabled;
+        if (pickColorChanged) {
+            sprite._pickColor.copy(sprite.pickColor);
+            attributesData.aPickColorAndEnabled[idx] = sprite._pickColor.r;
+            attributesData.aPickColorAndEnabled[idx + 1] = sprite._pickColor.g;
+            attributesData.aPickColorAndEnabled[idx + 2] = sprite._pickColor.b;
+        }
+        if (enablePickColorChanged) {
+            sprite._enablePickColor = sprite.enablePickColor;
+            attributesData.aPickColorAndEnabled[idx + 3] = sprite._enablePickColor ? 1 : 0;
+        }
+        mesh.geometry.attributes.aPickColorAndEnabled.needsUpdate = true;
+    }
 };
 /**
  * 添加一个InstancedSprite实例的数据到InstancedBufferAttribute中对应的位置

package/src/InstancedSpriteNodeMaterial.js

@@ -42,6 +42,7 @@ class InstancedSpriteNodeMaterial extends NodeMaterial {
         const aCenterAndSize = attribute('aCenterAndSize', 'vec4');
         const aScaleAndRotationAndSizeAttenuation = attribute('aScaleAndRotationAndSizeAttenuation', 'vec3');
         const aColorAndOpacity = attribute('aColorAndOpacity', 'vec4');
+        const aPickColorAndEnabled = attribute('aPickColorAndEnabled', 'vec4');
 
         // ============================================================
         // Varying 变量 — 从顶点着色器传递到片元着色器
@@ -49,6 +50,7 @@ class InstancedSpriteNodeMaterial extends NodeMaterial {
         const vShow = varying(float(1));
         const vColorAndOpacity = varying(vec4(1));
         const vUv = varying(vec2(1));
+        const vPickColorAndEnabled = varying(vec4(1));
 
         // ============================================================
         // 顶点着色器 (vertexNode)
@@ -66,6 +68,7 @@ class InstancedSpriteNodeMaterial extends NodeMaterial {
             vShow.assign(show);
             vColorAndOpacity.assign(aColorAndOpacity);
             vUv.assign(uv());
+            vPickColorAndEnabled.assign(aPickColorAndEnabled);
 
             // --- 3. 计算模型视图位置 ---
             const mvPosition = modelViewMatrix.mul(vec4(aPositionAndShow.xyz, 1));
@@ -122,12 +125,24 @@ class InstancedSpriteNodeMaterial extends NodeMaterial {
         // 片元着色器 (fragmentNode)
         // ============================================================
         this.fragmentNode = Fn(() => {
-            // 采样纹理
-            const texColor = texture(this._textureNode, vUv);
-            const diffuseColor = texColor.mul(vColorAndOpacity);
+            Discard(vShow.lessThan(0.5));
 
-            // 丢弃完全透明或隐藏的像素
-            Discard(diffuseColor.a.lessThan(0.005).or(vShow.lessThan(0.5)));
+            const enablePickColor = vPickColorAndEnabled.w.greaterThan(0.5);
+            const diffuseColor = vec4(0, 0, 0, 1).toVar('diffuseColor');
+
+            If(enablePickColor, () => {
+                // 拾取模式：直接输出拾取颜色，不受纹理/透明度影响
+                diffuseColor.assign(vec4(vPickColorAndEnabled.xyz, 1));
+            }).Else(() => {
+                // 采样纹理
+                const texColor = texture(this._textureNode, vUv);
+                const color = texColor.mul(vColorAndOpacity);
+
+                // 丢弃完全透明的像素
+                Discard(color.a.lessThan(0.005));
+
+                diffuseColor.assign(color);
+            });
 
             return diffuseColor;
         }).once();
@@ -142,7 +157,7 @@ class InstancedSpriteNodeMaterial extends NodeMaterial {
     set texture(value) {
         this._textureNode.value = value;
     }
-}
+};
 
 export default InstancedSpriteNodeMaterial;
 export { InstancedSpriteNodeMaterial };