@lijuhong1981/three.instancedsprite 1.0.1 → 2.0.0

package/src/InstancedSpriteNodeMaterial.js

@@ -43,6 +43,7 @@ class InstancedSpriteNodeMaterial extends NodeMaterial {
         const aScaleAndRotationAndSizeAttenuation = attribute('aScaleAndRotationAndSizeAttenuation', 'vec3');
         const aColorAndOpacity = attribute('aColorAndOpacity', 'vec4');
         const aPickColorAndEnabled = attribute('aPickColorAndEnabled', 'vec4');
+        const aUvRect = attribute('aUvRect', 'vec4');
 
         // ============================================================
         // Varying 变量 — 从顶点着色器传递到片元着色器
@@ -67,7 +68,7 @@ class InstancedSpriteNodeMaterial extends NodeMaterial {
             // --- 2. 输出 varying ---
             vShow.assign(show);
             vColorAndOpacity.assign(aColorAndOpacity);
-            vUv.assign(uv());
+            vUv.assign(aUvRect.xy.add(uv().mul(aUvRect.zw)));
             vPickColorAndEnabled.assign(aPickColorAndEnabled);
 
             // --- 3. 计算模型视图位置 ---
@@ -84,8 +85,8 @@ class InstancedSpriteNodeMaterial extends NodeMaterial {
 
             If(isVisible, () => {
                 // --- 4. sizeAttenuation：大小跟随相机深度 ---
-                // 检查是否为透视投影: 透视投影矩阵中 m[2][3] (elements[11]) == -1
-                const scaleFactor = sizeAttenuation.lessThan(0.5).and(cameraProjectionMatrix.element(11).equal(-1))
+                // 检查是否为透视投影：透视投影矩阵 m[2][3] (elements[11]) == -1
+                const scaleFactor = sizeAttenuation.lessThan(0.5).and(cameraProjectionMatrix.element(2).w.equal(-1))
                     .select(scale.mul(depth), scale);
 
                 // --- 5. 坐标对齐 ---
@@ -119,7 +120,7 @@ class InstancedSpriteNodeMaterial extends NodeMaterial {
             });
 
             return clipPosition;
-        }).once();
+        }).once()();
 
         // ============================================================
         // 片元着色器 (fragmentNode)
@@ -145,7 +146,7 @@ class InstancedSpriteNodeMaterial extends NodeMaterial {
             });
 
             return diffuseColor;
-        }).once();
+        }).once()();
     }
     /**
      * 图片纹理
@@ -161,3 +162,9 @@ class InstancedSpriteNodeMaterial extends NodeMaterial {
 
 export default InstancedSpriteNodeMaterial;
 export { InstancedSpriteNodeMaterial };
+/**
+ * InstancedSpriteNodeMaterial 的别名。
+ * @class
+ * @name BillboardNodeMaterial
+ */
+export const BillboardNodeMaterial = InstancedSpriteNodeMaterial;

package/src/TextureAtlas.js

@@ -0,0 +1,125 @@
+import { CanvasTexture } from "three";
+
+/**
+ * 纹理图集，将多张图片按行（shelf）打包进一张 Canvas 纹理，用于合并 draw call
+ */
+class TextureAtlas {
+    /**
+     * @param {object} [options]
+     * @param {number} [options.initialSize=1024] 初始边长（正方形，单位像素）
+     * @param {number} [options.maxSize=8192] 最大边长，自动扩容到该值后不再增大
+     * @param {number} [options.padding=2] 子图间距，防止线性过滤时边缘渗色
+    */
+    constructor(options = {}) {
+        this.initialSize = options.initialSize || 1024;
+        this.maxSize = options.maxSize || 8192;
+        this.padding = options.padding !== undefined ? options.padding : 2;
+
+        this.size = this.initialSize;
+        this.canvas = document.createElement('canvas');
+        this.canvas.width = this.size;
+        this.canvas.height = this.size;
+        this.ctx = this.canvas.getContext('2d');
+
+        this.texture = new CanvasTexture(this.canvas);
+        this.texture.needsUpdate = true;
+
+        this._cursorX = this.padding;
+        this._cursorY = this.padding;
+        this._rowHeight = 0;
+        this._rects = new Map(); // source -> {x, y, w, h} 像素矩形
+    }
+    /**
+     * 将图片加入图集，返回其像素矩形；已加入过则返回缓存；图集整体已满则返回null
+     * @param {HTMLImageElement|HTMLCanvasElement} source
+     * @returns {{x:number,y:number,w:number,h:number}|null}
+    */
+    add(source) {
+        const cached = this._rects.get(source);
+        if (cached) return cached;
+
+        const w = source.width;
+        const h = source.height;
+        const stepW = w + this.padding * 2;
+        const stepH = h + this.padding * 2;
+
+        // 单张图片超过当前图集尺寸时，先扩容到能容纳
+        while (stepW > this.size || stepH > this.size) {
+            if (!this.grow()) {
+                throw new Error('TextureAtlas: 图片尺寸超过图集最大尺寸');
+            }
+        }
+
+        // 当前行放不下则换行
+        if (this._cursorX + stepW > this.size) {
+            this._cursorX = this.padding;
+            this._cursorY += this._rowHeight;
+            this._rowHeight = 0;
+        }
+        // 图集整体已满
+        if (this._cursorY + stepH > this.size) {
+            return null;
+        }
+
+        const x = this._cursorX + this.padding;
+        const y = this._cursorY + this.padding;
+        const rect = { x, y, w, h };
+        this._rects.set(source, rect);
+
+        this.ctx.drawImage(source, x, y, w, h);
+
+        this._cursorX += stepW;
+        this._rowHeight = Math.max(this._rowHeight, stepH);
+
+        this.texture.needsUpdate = true;
+        return rect;
+    }
+    /**
+     * 获取图片已分配的像素矩形
+     * @param {HTMLImageElement|HTMLCanvasElement} source
+     * @returns {{x:number,y:number,w:number,h:number}|undefined}
+    */
+    getRect(source) {
+        return this._rects.get(source);
+    }
+    /**
+     * 扩容图集（边长翻倍），成功返回true；已达最大尺寸返回false
+     * @returns {boolean}
+    */
+    grow() {
+        const newSize = this.size * 2;
+        if (newSize > this.maxSize) return false;
+
+        const newCanvas = document.createElement('canvas');
+        newCanvas.width = newSize;
+        newCanvas.height = newSize;
+        const newCtx = newCanvas.getContext('2d');
+        newCtx.drawImage(this.canvas, 0, 0);
+
+        this.canvas = newCanvas;
+        this.ctx = newCtx;
+        this.size = newSize;
+
+        // 尺寸变化必须重建纹理：WebGL2 用 texStorage 分配固定尺寸，替换 image 后 texSubImage2D 无法扩容
+        this.texture.dispose();
+        this.texture = new CanvasTexture(this.canvas);
+        this.texture.needsUpdate = true;
+        return true;
+    }
+    /**
+     * 将像素矩形转为归一化 UV（uOffset, vOffset, uScale, vScale）
+     * @param {{x:number,y:number,w:number,h:number}} rect
+     * @returns {Array<number>}
+    */
+    getUvRect(rect) {
+        return [
+            rect.x / this.size,
+            1 - (rect.y + rect.h) / this.size, // flipY=true 时纹理上下翻转，v 坐标需反转
+            rect.w / this.size,
+            rect.h / this.size,
+        ];
+    }
+}
+
+export default TextureAtlas;
+export { TextureAtlas };

package/.claude/settings.local.json

@@ -1,7 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(node --check src/InstancedSpriteNodeMaterial.js)"
-    ]
-  }
-}