@lijuhong1981/three.instancedsprite 1.0.0

package/src/InstancedSprite.js

@@ -0,0 +1,345 @@
+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 InstancedSpriteCollection from "./InstancedSpriteCollection.js";
+ * @import InstancedSpriteMesh from "./InstancedSpriteMesh.js";
+ * @import InstancedSpriteMaterial from "./InstancedSpriteMaterial.js";
+ */
+
+const imageLoader = new ImageLoader({ cacheType: Loader.CacheType.ALONE, });
+
+const _intersectPoint = /*@__PURE__*/ new Vector3();
+const _worldScale = /*@__PURE__*/ new Vector3();
+const _mvPosition = /*@__PURE__*/ new Vector3();
+
+const _alignedPosition = /*@__PURE__*/ new Vector2();
+const _rotatedPosition = /*@__PURE__*/ new Vector2();
+const _viewWorldMatrix = /*@__PURE__*/ new Matrix4();
+
+const _vA = /*@__PURE__*/ new Vector3();
+const _vB = /*@__PURE__*/ new Vector3();
+const _vC = /*@__PURE__*/ new Vector3();
+
+const _uvA = /*@__PURE__*/ new Vector2();
+const _uvB = /*@__PURE__*/ new Vector2();
+const _uvC = /*@__PURE__*/ new Vector2();
+
+function transformVertex(vertexPosition, mvPosition, center, scale, sin, cos) {
+
+    // compute position in camera space
+    _alignedPosition.subVectors(vertexPosition, center).addScalar(0.5).multiply(scale);
+
+    // to check if rotation is not zero
+    if (sin !== undefined) {
+
+        _rotatedPosition.x = (cos * _alignedPosition.x) - (sin * _alignedPosition.y);
+        _rotatedPosition.y = (sin * _alignedPosition.x) + (cos * _alignedPosition.y);
+
+    } else {
+
+        _rotatedPosition.copy(_alignedPosition);
+
+    }
+
+
+    vertexPosition.copy(mvPosition);
+    vertexPosition.x += _rotatedPosition.x;
+    vertexPosition.y += _rotatedPosition.y;
+
+    // transform to world space
+    vertexPosition.applyMatrix4(_viewWorldMatrix);
+
+}
+
+/**
+ * InstancedSprite 对象配置项选项
+ * @typedef {object} InstancedSpriteOptions
+ * @property {boolean} [show=true] 是否显示
+ * @property {Vector3|Array<number>} [position=(0,0,0)] 位置（世界空间）
+ * @property {number} [scale=1] 缩放
+ * @property {number} [rotation=0] 旋转（弧度）
+ * @property {boolean} [sizeAttenuation=true] 尺寸是否跟随相机深度变化
+ * @property {Vector2|Array<number>} [center=(0.5,0.5)] 锚点中心（0-1）
+ * @property {Color|number|string} [color=0xffffff] 颜色
+ * @property {number} [opacity=1] 不透明度（0-1）
+ * @property {string|HTMLImageElement|HTMLCanvasElement} [image] 图片资源
+ */
+
+/**
+ * InstancedSprite 数据模型类，用于存储单个 InstancedSprite 的所有属性
+ *
+ * * InstancedSprite跟Sprite不同，它只是一个数据集合对象，并不继承自Object3D，不能直接加入到Scene中
+ * * 但它可以作为属性Module使用，修改InstancedSprite的属性会自动更新至GPU中
+ */
+class InstancedSprite {
+    /**
+     * @param {InstancedSpriteOptions} options - 初始化配置项
+     * @param {InstancedSpriteCollection} collection - 所属InstancedSpriteCollection实例，必填
+     * @constructor
+     */
+    constructor(options = {}, collection) {
+        Check.defined('collection', collection);
+        /**
+         * 所属集合，内部设置
+         * @type {InstancedSpriteCollection}
+         * @ignore
+        */
+        this._collection = collection;
+        /**
+         * 所属Mesh，内部设置
+         * @type {InstancedSpriteMesh}
+         * @ignore
+        */
+        this._mesh = undefined;
+        /**
+         * 在 InstancedSpriteMesh 中的实例索引，由 InstancedSpriteMesh 内部设置
+         * @type {number}
+         * @ignore
+        */
+        this._instanceIndex = -1;
+        /**
+         * 对象类型标识
+         * @type {string}
+         * @readonly
+        */
+        this.type = "InstancedSprite";
+        /**
+         * 当前InstancedSprite的唯一标识id
+         * @type {string}
+         * @readonly
+        */
+        this.uuid = MathUtils.generateUUID();
+        /**
+         * 是否显示 
+         * @type {boolean}
+         */
+        this.show = true;
+        this._show = true;
+        /** 
+         * 世界坐标位置
+         * @type {Vector3} 
+         */
+        this.position = new Vector3(0, 0, 0);
+        this._position = new Vector3(0, 0, 0);
+        /**
+         * 缩放
+         * @type {number}
+        */
+        this.scale = 1;
+        this._scale = 1;
+        /**
+         * 旋转（弧度）
+         * @type {number}
+        */
+        this.rotation = 0;
+        this._rotation = 0;
+        /**
+         * 尺寸是否跟随相机深度变化
+         * @type {boolean}
+        */
+        this.sizeAttenuation = true;
+        this._sizeAttenuation = true;
+        /**
+         * 锚点中心（0-1）
+         * @type {Vector2}
+        */
+        this.center = new Vector2(0.5, 0.5);
+        this._center = new Vector2(0.5, 0.5);
+        /**
+         * 颜色
+         * @type {Color}
+        */
+        this.color = new Color(0xffffff);
+        this._color = new Color(0xffffff);
+        /**
+         * 不透明度（0-1）
+         * @type {number}
+        */
+        this.opacity = 1;
+        this._opacity = 1;
+        /**
+         * 图片尺寸（像素），图片加载完成后可用
+         * @type {Vector2}
+         * @readonly
+        */
+        this.imageSize = new Vector2(0, 0);
+        this._imageSize = new Vector2(0, 0);
+        this._image = null;
+
+        this.setValues(options);
+    }
+    /** 
+     * InstancedSprite对象标识
+     * @type {boolean} 
+     * @readonly
+     */
+    get isInstancedSprite() { return true; }
+    /**
+     * 设置参数
+     * @param {InstancedSpriteOptions} options
+     * @returns {InstancedSprite}
+    */
+    setValues(options) {
+        setValues(this, options);
+        return this;
+    }
+    /**
+     * 是否可见，等同于show 
+     * @type {boolean}
+     */
+    get visible() {
+        return this.show;
+    }
+    set visible(value) { this.show = value; }
+    /**
+     * 旋转（角度）
+     * @type {number}
+    */
+    get rotationDegrees() { return MathUtils.radToDeg(this.rotation); }
+    set rotationDegrees(value) { this.rotation = MathUtils.degToRad(value); }
+    /** 
+     * 图片资源，可以是URL字符串、HTMLImageElement或HTMLCanvasElement
+     * @type {string|HTMLImageElement|HTMLCanvasElement}
+    */
+    get image() { return this._image; }
+    set image(value) {
+        if (this._image) {
+            if (typeof value === 'string') {
+                if (this._image.src === value)
+                    return;
+            } else if (value instanceof HTMLImageElement || value instanceof HTMLCanvasElement) {
+                if (this._image === value)
+                    return;
+            }
+        }
+        this._collection._setImage(value, this);
+    }
+    /**
+     * 图片ID，图片加载完成后可用，通常为图片URL或生成的UUID
+     * @type {string}
+     * @readonly
+    */
+    get imageId() { return this._image && this._image.src; }
+    /**
+     * 图片像素宽度，图片加载完成后可用
+     * @type {number}
+     * @readonly
+    */
+    get imageWidth() { return this.imageSize.x; }
+    /**
+     * 图片像素高度，图片加载完成后可用
+     * @type {number}
+     * @readonly
+    */
+    get imageHeight() { return this.imageSize.y; }
+    _remove() {
+        this._mesh && this._mesh.remove(this);
+        return this;
+    }
+    /**
+     * InstancedSprite对象的几何体属性
+     * @type {InstancedBufferGeometry}
+     * @readonly
+    */
+    get geometry() {
+        return this._mesh ? this._mesh.geometry : undefined;
+    }
+    /**
+     * InstancedSprite对象的材质属性
+     * @type {InstancedSpriteMaterial}
+     * @readonly
+    */
+    get material() {
+        return this._mesh ? this._mesh.material : undefined;
+    }
+    /**
+     * 从Mesh中移除该InstancedSprite对象
+     * @return {InstancedSprite}
+    */
+    remove() {
+        this._collection && this._collection.remove(this);
+        return this;
+    }
+    /**
+     * Computes intersection points between a casted ray and this sprite.
+     *
+     * @param {Raycaster} raycaster - The raycaster.
+     * @param {Array<Object>} intersects - The target array that holds the intersection points.
+     * @param {Matrix4} modelViewMatrix
+     */
+    raycast(raycaster, intersects, modelViewMatrix) {
+
+        if (this.show === false || this.imageSize.x <= 0 || this.imageSize.y <= 0) {
+            return;
+        }
+
+        _viewWorldMatrix.copy(raycaster.camera.matrixWorld);
+        _mvPosition.copy(this.position).applyMatrix4(modelViewMatrix);
+
+        const depth = -_mvPosition.z;
+        if (depth <= 0) {
+            return;
+        }
+
+        let scale = this.scale;
+        if (raycaster.camera.isPerspectiveCamera && this.sizeAttenuation === false) {
+            scale *= depth;
+        }
+        const aspectRatio = this.imageSize.x / this.imageSize.y;
+        _worldScale.set(1, 1, 1).multiplyScalar(scale * aspectRatio);
+
+        const rotation = this.rotation;
+        let sin, cos;
+
+        if (rotation !== 0) {
+            cos = Math.cos(rotation);
+            sin = Math.sin(rotation);
+        }
+
+        const center = this.center;
+
+        transformVertex(_vA.set(-0.5, -0.5, 0), _mvPosition, center, _worldScale, sin, cos);
+        transformVertex(_vB.set(0.5, -0.5, 0), _mvPosition, center, _worldScale, sin, cos);
+        transformVertex(_vC.set(0.5, 0.5, 0), _mvPosition, center, _worldScale, sin, cos);
+
+        _uvA.set(0, 0);
+        _uvB.set(1, 0);
+        _uvC.set(1, 1);
+
+        // check first triangle
+        let intersect = raycaster.ray.intersectTriangle(_vA, _vB, _vC, false, _intersectPoint);
+
+        if (intersect === null) {
+
+            // check second triangle
+            transformVertex(_vB.set(-0.5, 0.5, 0), _mvPosition, center, _worldScale, sin, cos);
+            _uvB.set(0, 1);
+
+            intersect = raycaster.ray.intersectTriangle(_vA, _vC, _vB, false, _intersectPoint);
+            if (intersect === null) {
+                return;
+            }
+
+        }
+
+        const distance = raycaster.ray.origin.distanceTo(_intersectPoint);
+
+        if (distance < raycaster.near || distance > raycaster.far) return;
+
+        intersects.push({
+            distance: distance,
+            point: _intersectPoint.clone(),
+            uv: Triangle.getInterpolation(_intersectPoint, _vA, _vB, _vC, _uvA, _uvB, _uvC, new Vector2()),
+            face: null,
+            object: this,
+            instanceId: this._instanceIndex,
+        });
+    }
+};
+
+export default InstancedSprite;
+export { InstancedSprite };

package/src/InstancedSpriteCollection.js

@@ -0,0 +1,226 @@
+import Check from "@lijuhong1981/jscheck/src/Check.js";
+import {
+    MathUtils,
+    Object3D,
+    Texture
+} from "three";
+import InstancedSprite from "./InstancedSprite.js";
+import InstancedSpriteMesh from "./InstancedSpriteMesh.js";
+
+/**
+ * @import InstancedSpriteOptions from "./InstancedSprite.js";
+*/
+
+/**
+ * @type {Map<string, HTMLImageElement|HTMLCanvasElement>}
+ * @ignore
+*/
+const imageCache = new Map();
+
+/**
+ * InstancedSpriteCollection类，批量管理InstancedSprite实例
+ * 
+ * * 继承自Object3D
+ * * 根据InstancedSprite的图像属性生成InstancedSpriteMaterial和InstancedSpriteMesh，
+ * * 管理InstancedSprite与InstancedSpriteMesh实例
+ * @extends Object3D
+ */
+class InstancedSpriteCollection extends Object3D {
+    /**
+     * @param {boolean} [useNodeMaterial=false] - 是否使用TSL的NodeMaterial，默认false
+     * @constructor
+    */
+    constructor(useNodeMaterial = false) {
+        super();
+        /**
+         * 是否使用TSL的NodeMaterial，默认false
+         * @type {boolean}
+         * @readonly
+         * @default false
+        */
+        this.useNodeMaterial = useNodeMaterial;
+        /**
+         * 对象类型标识
+         * @type {string}
+         * @readonly
+        */
+        this.type = "InstancedSpriteCollection";
+        // this.frustumCulled = false;
+        /**
+         * @type {Array<InstancedSprite>}
+         * @ignore
+        */
+        this._instancedSprites = [];
+        /**
+         * @type {Map<HTMLImageElement|HTMLCanvasElement, InstancedSpriteMesh>}
+         * @ignore
+        */
+        this._meshes = new Map();
+        this._depthTest = true;
+    }
+    /**
+     * InstancedSpriteCollection对象标识
+     * @type {boolean}
+     * @readonly
+    */
+    get isInstancedSpriteCollection() { return true; }
+    /**
+     * 深度测试开关，默认为true，开启后会进行深度测试以正确处理遮挡关系，但可能会有性能影响；如果关闭则所有InstancedSprite都会被渲染在最前面，适合需要始终显示的UI元素等场景
+     * @type {boolean}
+     * @default true
+    */
+    get depthTest() { return this._depthTest; }
+    set depthTest(value) {
+        Check.typeOf.boolean(value, 'depthTest');
+        this._depthTest = value;
+        const meshes = this._meshes.values();
+        for (const mesh of meshes) {
+            mesh.depthTest = value;
+        }
+    }
+    /**
+     * @param {string|HTMLImageElement|HTMLCanvasElement} source
+     * @param {InstancedSprite} sprite
+    */
+    _setImage(source, sprite) {
+        if (source instanceof HTMLImageElement || source instanceof HTMLCanvasElement) {
+            if (!source.src)
+                source.src = MathUtils.generateUUID();
+            if (!imageCache.has(source.src))
+                imageCache.set(source.src, source);
+            let mesh = this._meshes.get(source);
+            if (!mesh) {
+                const texture = new Texture();
+                if (source instanceof HTMLCanvasElement || (source instanceof HTMLImageElement && source.complete)) {
+                    texture.image = source;
+                    texture.needsUpdate = true;
+                } else {
+                    const onload = () => {
+                        source.removeEventListener('load', onload);
+                        texture.image = source;
+                        texture.needsUpdate = true;
+                        sprite.imageSize.set(source.width, source.height);
+                    };
+                    source.addEventListener('load', onload);
+                }
+                mesh = new InstancedSpriteMesh(this, texture);
+                mesh.depthTest = this._depthTest;
+                this._meshes.set(source, mesh);
+                super.add(mesh);
+            }
+            if (sprite._mesh === mesh)
+                return;
+            // instancedSprite如果已经有所属的mesh了，则从所属的Mesh中移除
+            sprite.remove();
+            mesh.add(sprite);
+            sprite._image = source;
+            if (source.width !== 0 && source.height !== 0) {
+                sprite.imageSize.set(source.width, source.height);
+            }
+        } else if (typeof source === 'string') {
+            let image = imageCache.get(source);
+            if (!image) {
+                image = new Image();
+                image.src = source;
+                imageCache.set(source, image);
+            }
+            this._setImage(image, sprite);
+        } else {
+            throw new Error('Invalid image source type ' + source);
+        }
+    }
+    /**
+     * InstancedSprite实例数组
+     * @type {Array<InstancedSprite>}
+     * @readonly
+    */
+    get instancedSprites() {
+        return this._instancedSprites;
+    }
+    /**
+     * InstancedSprite实例数量
+     * @type {number}
+     * @readonly
+    */
+    get size() {
+        return this._instancedSprites.length;
+    }
+    /**
+     * 根据索引获取InstancedSprite实例
+     * @param {number} index 
+     * @returns {InstancedSprite|undefined}
+    */
+    get(index) {
+        return this._instancedSprites[index];
+    }
+    /**
+     * 根据uuid获取InstancedSprite实例
+     * @param {string} uuid
+     * @returns {InstancedSprite|undefined}
+    */
+    getByUuid(uuid) {
+        for (const sprite of this._instancedSprites) {
+            if (sprite.uuid === uuid)
+                return sprite;
+        }
+    }
+    /**
+     * 添加InstancedSprite
+     * @type {InstancedSpriteConstructorOptions} options
+     * @returns {InstancedSprite}
+    */
+    add(options = {}) {
+        const sprite = new InstancedSprite(options, this);
+        this._instancedSprites.push(sprite);
+        return sprite;
+    }
+    /**
+     * 移除InstancedSprite
+     * @param {InstancedSprite} sprite
+     * @returns {InstancedSpriteCollection}
+    */
+    remove(sprite) {
+        const index = this._instancedSprites.indexOf(sprite);
+        if (index !== -1) {
+            this._instancedSprites.splice(index, 1);
+            sprite._remove();
+        }
+        return this;
+    }
+    /**
+     * 遍历所有的InstancedSprite
+     * @param {Function} callback
+     * @returns {InstancedSpriteCollection}
+    */
+    forEach(callback) {
+        this._instancedSprites.forEach(callback);
+        return this;
+    }
+    /**
+     * Computes intersection points between a casted ray and this sprite.
+     *
+     * @param {Raycaster} raycaster - The raycaster.
+     * @param {Array<Object>} intersects - The target array that holds the intersection points.
+     */
+    raycast(raycaster, intersects) {
+        const meshes = this._meshes.values();
+        for (const mesh of meshes) {
+            mesh.raycast(raycaster, intersects);
+        }
+    }
+    /**
+     * 每帧更新
+     * @private
+     */
+    update() {
+        if (!this.visible) return;
+
+        const meshes = this._meshes.values();
+        for (const mesh of meshes) {
+            mesh.update();
+        }
+    }
+};
+
+export default InstancedSpriteCollection;
+export { InstancedSpriteCollection };

package/src/InstancedSpriteMaterial.js

@@ -0,0 +1,134 @@
+import { ShaderMaterial, Texture } from "three";
+
+const vertexShader = `
+// Three.js ShaderMaterial专用，自动注入uv、position、modelViewMatrix、projectionMatrix
+precision highp float;
+precision highp int;
+
+#include <common>
+#include <logdepthbuf_pars_vertex>
+
+// 基础属性
+attribute vec4 aPositionAndShow; // xyz: InstancedSprite位置（世界空间），w：显示标志(0/1)
+attribute vec4 aCenterAndSize; // xy: 锚点中心(0-1), zw: 图片宽高(像素/米)
+attribute vec3 aScaleAndRotationAndSizeAttenuation; // x: 缩放, y: 旋转(弧度), z: 大小跟随相机深度(0/1)
+attribute vec4 aColorAndOpacity; // RGBA颜色
+
+varying float vShow;
+varying vec2 vUv;
+varying vec4 vColorAndOpacity;
+
+void main() {
+    // --- 1. 提前解包属性（GPU会自动优化，无性能损失）---
+    float show = aPositionAndShow.w;
+    float scale = aScaleAndRotationAndSizeAttenuation.x;
+    float rotation = aScaleAndRotationAndSizeAttenuation.y;
+    float sizeAttenuation = aScaleAndRotationAndSizeAttenuation.z;
+    vec2 center = aCenterAndSize.xy;
+    vec2 imageSize = aCenterAndSize.zw;
+
+    // --- 2. 输出varying变量 ---
+    vShow = show;
+    vUv = uv;
+    vColorAndOpacity = aColorAndOpacity;
+
+    // --- 3. 提前隐藏不可见物体（顶点级丢弃，性能最优）---
+    if (show < 0.5 || imageSize.x <= 0.0 || imageSize.y <= 0.0) {
+        vShow = 0.0;
+        gl_Position = vec4(0.0, 0.0, 2.0, 1.0);
+        return;
+    }
+
+    // --- 4. 计算模型视图位置 ---
+    vec4 mvPosition = modelViewMatrix * vec4(aPositionAndShow.xyz, 1.0);
+
+    // --- 5. 深度检查：隐藏相机后面的物体，避免尺寸翻转 ---
+    float depth = -mvPosition.z;
+    if (depth <= 0.0) {
+        vShow = 0.0;
+        gl_Position = vec4(0.0, 0.0, 2.0, 1.0);
+        return;
+    }
+
+    // --- 6. sizeAttenuation检查：大小跟随深度
+    if (sizeAttenuation < 0.5) {
+        bool isPerspective = isPerspectiveMatrix( projectionMatrix );
+		if ( isPerspective ) scale *= depth;
+    }
+
+    // --- 7. 坐标对齐
+    float aspectRatio = imageSize.x / imageSize.y;
+    vec2 alignedPosition = ( position.xy - ( center - vec2( 0.5 ) ) ) * aspectRatio * scale;
+
+    // --- 8. 计算旋转
+	vec2 rotatedPosition;
+	rotatedPosition.x = cos( rotation ) * alignedPosition.x - sin( rotation ) * alignedPosition.y;
+	rotatedPosition.y = sin( rotation ) * alignedPosition.x + cos( rotation ) * alignedPosition.y;
+	mvPosition.xy += rotatedPosition;
+
+    // --- 9. 投影变换 ---
+    gl_Position = projectionMatrix * mvPosition;
+
+    #include <logdepthbuf_vertex>
+}
+`;
+
+const fragmentShader = `
+uniform sampler2D uTexture;
+
+#include <common>
+#include <logdepthbuf_pars_fragment>
+
+varying float vShow;
+varying vec2 vUv;
+varying vec4 vColorAndOpacity;
+
+void main() {
+    vec4 texColor = texture2D(uTexture, vUv);
+    vec4 diffuseColor = texColor * vColorAndOpacity;
+
+    // 丢弃完全透明的像素
+    if (diffuseColor.a < 0.005 || vShow < 0.5) {
+        discard;
+    }
+
+    gl_FragColor = diffuseColor;
+
+    #include <logdepthbuf_fragment>
+    #include <tonemapping_fragment>
+	#include <colorspace_fragment>
+}
+`;
+
+/**
+ * InstancedSprite 材质类，以attribute形式传入InstancedSprite对象实例属性
+ * 
+ * @extends ShaderMaterial
+*/
+class InstancedSpriteMaterial extends ShaderMaterial {
+    constructor() {
+        super({
+            vertexShader,
+            fragmentShader,
+            uniforms: {
+                uTexture: { value: null },
+            },
+            transparent: true,
+            depthTest: true,
+            depthWrite: true,
+        });
+    }
+    /**
+     * 图片纹理
+     * @type {Texture}
+    */
+    set texture(value) {
+        this.uniforms.uTexture.value = value;
+    }
+    get texture() {
+        return this.uniforms.uTexture.value;
+    }
+};
+
+export default InstancedSpriteMaterial;
+export { InstancedSpriteMaterial };