three-base 2.0.142 → 2.0.166

package/lensflare/LensFlare.js

@@ -1,50 +1,50 @@
-/*
- * @Author: xiaosihan
- * @Date: 2026-08-14
- * @Last Modified by: xiaosihan
- * @Last Modified time: 2026-08-16
- * @Description: 镜头光晕（Lens Flare）组件。
- *   内联 fork 自 three r167 的 examples/jsm/objects/Lensflare.js（仅复用官方 LensflareElement 作为数据容器）。
- *   正对强光源（太阳）时沿「光源→屏幕中心」连线生成一串彩色光环/鬼影，并做遮挡判断。
- *   光晕素材为自定义 PNG（lensflare_custom.png，来自用户提供的「preview_png.png」），
- *   靠 LensflareElement 的 color 叠加染色（默认橙色）。
- *   每个实例用 TextureLoader 独立加载素材成独立纹理，故 dispose 时只释放自己的，互不影响。
- *   布局：主光点(mainSize@0，最小) + 4 鬼影(100/140/180/220 @ 0.6/0.7/0.9/1，越靠近屏幕中心越大) + 光源背面 3 光斑(40/70/50 @ -0.2/-0.45/-0.7，小)。
- *
- *   【与官方源码的关键差异】去除了「光源超出屏幕范围(validArea.containsPoint)则整串不渲染」的 screen cull：
- *     官方把"光源在屏幕内"作为主光点 + 全部鬼影的统一渲染前提，光源一出屏幕，整串光晕消失。
- *     本项目改为「始终渲染鬼影串」——GPU 会自动裁剪超出屏幕的 quad，落进屏幕内的鬼影部分照常显示；
- *     仅当光源在屏幕内(onScreen)时才做遮挡采样(occlusion)，光源在屏幕外时越界采样无意义，
- *     改用 occlusionForceVisible=1 强制可见（避免遮挡图采样越界得到全黑→鬼影被 vVisibility 乘成透明）。
- *     相机背后(positionView.z>0)仍不显示——那是几何上光源在视线后方，光晕本无意义，不属于"超出屏幕"。
- */
-import { AdditiveBlending, Box2, BufferGeometry, Color, FramebufferTexture, InterleavedBuffer, InterleavedBufferAttribute, Mesh, MeshBasicMaterial, RawShaderMaterial, Scene, UnsignedByteType, Vector2, Vector3, Vector4 } from "three";
-import { LensflareElement } from "three/examples/jsm/objects/Lensflare.js";
-import { TextureLoader } from "three";
-import customPNG from "./lensflare_custom.png";
-// 复用同一 loader，但 load() 每次返回独立 Texture 对象（加载同一 URL 也互不共享），dispose 安全
-const textureLoader = new TextureLoader();
-// 每个 LensFlare 实例有独立的 overlayScene（含 mesh2），
-// 屏幕叠加阶段用 renderer.render(scene, camera) 而非 renderBufferDirect，
-// 因为 renderBufferDirect 依赖 renderer.render 流程初始化的 currentRenderState，
-// 而在 ThreeBase 终处理之后调用时 currentRenderState 已被清空，会 null.state 崩溃。
-// 所有存活的 LensFlare 实例（构造时注册、dispose 时注销）。
-// 渲染器每帧在屏幕输出后调用 flushLensflareOverlays() 统一叠加所有可见鬼影，
-// 无需 ThreeBase 遍历场景或依赖 renderer 事件系统（避免 addEventListener 兼容问题）。
-const lensflareInstances = new Set();
-/**
- * 屏幕叠加入口：渲染器在最终画面输出到屏幕后调用一次，
- * 把所有本帧可见的 LensFlare 鬼影以加色混合叠加到当前屏幕帧缓冲。
- * 仅当 renderer 当前渲染目标为屏幕（null）时生效；中间后处理 target 调用会被忽略。
- * 不依赖具体渲染器类型（只要是 three WebGLRenderer），LensFlare 与 ThreeBase 零耦合。
- */
-export function flushLensflareOverlays(renderer, camera) {
-    if (renderer.getRenderTarget() !== null)
-        return;
-    lensflareInstances.forEach((lf) => lf.renderScreenOverlay(renderer, camera));
-}
-/** 鬼影元素着色器：在官方 LensflareElement.Shader 基础上新增 occlusionForceVisible uniform，
- *  当其为 1.0 时强制 vVisibility=1（光源在屏幕外、遮挡采样无意义时，让鬼影完全可见）。 */
+/*
+ * @Author: xiaosihan
+ * @Date: 2026-08-14
+ * @Last Modified by: xiaosihan
+ * @Last Modified time: 2026-08-16
+ * @Description: 镜头光晕（Lens Flare）组件。
+ *   内联 fork 自 three r167 的 examples/jsm/objects/Lensflare.js（仅复用官方 LensflareElement 作为数据容器）。
+ *   正对强光源（太阳）时沿「光源→屏幕中心」连线生成一串彩色光环/鬼影，并做遮挡判断。
+ *   光晕素材为自定义 PNG（lensflare_custom.png，来自用户提供的「preview_png.png」），
+ *   靠 LensflareElement 的 color 叠加染色（默认橙色）。
+ *   每个实例用 TextureLoader 独立加载素材成独立纹理，故 dispose 时只释放自己的，互不影响。
+ *   布局：主光点(mainSize@0，最小) + 4 鬼影(100/140/180/220 @ 0.6/0.7/0.9/1，越靠近屏幕中心越大) + 光源背面 3 光斑(40/70/50 @ -0.2/-0.45/-0.7，小)。
+ *
+ *   【与官方源码的关键差异】去除了「光源超出屏幕范围(validArea.containsPoint)则整串不渲染」的 screen cull：
+ *     官方把"光源在屏幕内"作为主光点 + 全部鬼影的统一渲染前提，光源一出屏幕，整串光晕消失。
+ *     本项目改为「始终渲染鬼影串」——GPU 会自动裁剪超出屏幕的 quad，落进屏幕内的鬼影部分照常显示；
+ *     仅当光源在屏幕内(onScreen)时才做遮挡采样(occlusion)，光源在屏幕外时越界采样无意义，
+ *     改用 occlusionForceVisible=1 强制可见（避免遮挡图采样越界得到全黑→鬼影被 vVisibility 乘成透明）。
+ *     相机背后(positionView.z>0)仍不显示——那是几何上光源在视线后方，光晕本无意义，不属于"超出屏幕"。
+ */
+import { AdditiveBlending, Box2, BufferGeometry, Color, FramebufferTexture, InterleavedBuffer, InterleavedBufferAttribute, Mesh, MeshBasicMaterial, RawShaderMaterial, Scene, UnsignedByteType, Vector2, Vector3, Vector4 } from "three";
+import { LensflareElement } from "three/examples/jsm/objects/Lensflare.js";
+import { TextureLoader } from "three";
+import customPNG from "./lensflare_custom.png";
+// 复用同一 loader，但 load() 每次返回独立 Texture 对象（加载同一 URL 也互不共享），dispose 安全
+const textureLoader = new TextureLoader();
+// 每个 LensFlare 实例有独立的 overlayScene（含 mesh2），
+// 屏幕叠加阶段用 renderer.render(scene, camera) 而非 renderBufferDirect，
+// 因为 renderBufferDirect 依赖 renderer.render 流程初始化的 currentRenderState，
+// 而在 ThreeBase 终处理之后调用时 currentRenderState 已被清空，会 null.state 崩溃。
+// 所有存活的 LensFlare 实例（构造时注册、dispose 时注销）。
+// 渲染器每帧在屏幕输出后调用 flushLensflareOverlays() 统一叠加所有可见鬼影，
+// 无需 ThreeBase 遍历场景或依赖 renderer 事件系统（避免 addEventListener 兼容问题）。
+const lensflareInstances = new Set();
+/**
+ * 屏幕叠加入口：渲染器在最终画面输出到屏幕后调用一次，
+ * 把所有本帧可见的 LensFlare 鬼影以加色混合叠加到当前屏幕帧缓冲。
+ * 仅当 renderer 当前渲染目标为屏幕（null）时生效；中间后处理 target 调用会被忽略。
+ * 不依赖具体渲染器类型（只要是 three WebGLRenderer），LensFlare 与 ThreeBase 零耦合。
+ */
+export function flushLensflareOverlays(renderer, camera) {
+    if (renderer.getRenderTarget() !== null)
+        return;
+    lensflareInstances.forEach((lf) => lf.renderScreenOverlay(renderer, camera));
+}
+/** 鬼影元素着色器：在官方 LensflareElement.Shader 基础上新增 occlusionForceVisible uniform，
+ *  当其为 1.0 时强制 vVisibility=1（光源在屏幕外、遮挡采样无意义时，让鬼影完全可见）。 */
 const LensflareElementVertexShader = /* glsl */ `
     precision highp float;
 
@@ -86,7 +86,7 @@ const LensflareElementVertexShader = /* glsl */ `
         gl_Position = vec4( ( pos * scale + screenPosition.xy ).xy, screenPosition.z, 1.0 );
 
     }
-`;
+`;
 const LensflareElementFragmentShader = /* glsl */ `
     precision highp float;
 
@@ -104,39 +104,39 @@ const LensflareElementFragmentShader = /* glsl */ `
         gl_FragColor.rgb *= color;
 
     }
-`;
-/** 内联 fork 自 three r167 的 Lensflare 主类（去除了屏幕外整体 cull）。
- *  仅在官方实现上做了两处改动：
- *   1) 移除 `if ( validArea.containsPoint(...) )` 对鬼影渲染的整体包裹，改为始终渲染；
- *   2) 新增 occlusionForceVisible uniform，光源在屏幕外时置 1 强制可见。 */
-class BaseLensflare extends Mesh {
-    static Geometry;
-    isLensflare;
-    addElement;
-    dispose;
-    /** 屏幕叠加：由模块级 flushLensflareOverlays() 在渲染器输出屏幕后统一调用，把鬼影画到当前帧缓冲。 */
-    renderScreenOverlay;
-    constructor() {
-        super(BaseLensflare.Geometry, new MeshBasicMaterial({ opacity: 0, transparent: true }));
-        // 注册进全局实例表，供 flushLensflareOverlays 统一叠加（不依赖 renderer 事件系统，避免 addEventListener 兼容问题）
-        lensflareInstances.add(this);
-        this.isLensflare = true;
-        this.type = "Lensflare";
-        this.frustumCulled = false;
-        this.renderOrder = Infinity;
-        // -- 以下变量与官方保持一致（闭包局部，供 onBeforeRender 使用） --
-        const positionScreen = new Vector3();
-        const positionView = new Vector3();
-        const tempMap = new FramebufferTexture(16, 16);
-        const occlusionMap = new FramebufferTexture(16, 16);
-        let currentType = UnsignedByteType;
-        const geometry = BaseLensflare.Geometry;
-        // 遮挡采样：在光源像素处画一个洋红 quad，再把该处像素拷进 occlusionMap（被遮挡则非洋红→变暗）
-        const material1a = new RawShaderMaterial({
-            uniforms: {
-                scale: { value: null },
-                screenPosition: { value: null }
-            },
+`;
+/** 内联 fork 自 three r167 的 Lensflare 主类（去除了屏幕外整体 cull）。
+ *  仅在官方实现上做了两处改动：
+ *   1) 移除 `if ( validArea.containsPoint(...) )` 对鬼影渲染的整体包裹，改为始终渲染；
+ *   2) 新增 occlusionForceVisible uniform，光源在屏幕外时置 1 强制可见。 */
+class BaseLensflare extends Mesh {
+    static Geometry;
+    isLensflare;
+    addElement;
+    dispose;
+    /** 屏幕叠加：由模块级 flushLensflareOverlays() 在渲染器输出屏幕后统一调用，把鬼影画到当前帧缓冲。 */
+    renderScreenOverlay;
+    constructor() {
+        super(BaseLensflare.Geometry, new MeshBasicMaterial({ opacity: 0, transparent: true }));
+        // 注册进全局实例表，供 flushLensflareOverlays 统一叠加（不依赖 renderer 事件系统，避免 addEventListener 兼容问题）
+        lensflareInstances.add(this);
+        this.isLensflare = true;
+        this.type = "Lensflare";
+        this.frustumCulled = false;
+        this.renderOrder = Infinity;
+        // -- 以下变量与官方保持一致（闭包局部，供 onBeforeRender 使用） --
+        const positionScreen = new Vector3();
+        const positionView = new Vector3();
+        const tempMap = new FramebufferTexture(16, 16);
+        const occlusionMap = new FramebufferTexture(16, 16);
+        let currentType = UnsignedByteType;
+        const geometry = BaseLensflare.Geometry;
+        // 遮挡采样：在光源像素处画一个洋红 quad，再把该处像素拷进 occlusionMap（被遮挡则非洋红→变暗）
+        const material1a = new RawShaderMaterial({
+            uniforms: {
+                scale: { value: null },
+                screenPosition: { value: null }
+            },
             vertexShader: /* glsl */ `
                 precision highp float;
                 uniform vec3 screenPosition;
@@ -145,24 +145,24 @@ class BaseLensflare extends Mesh {
                 void main() {
                     gl_Position = vec4( position.xy * scale + screenPosition.xy, screenPosition.z, 1.0 );
                 }
-            `,
+            `,
             fragmentShader: /* glsl */ `
                 precision highp float;
                 void main() {
                     gl_FragColor = vec4( 1.0, 0.0, 1.0, 1.0 );
                 }
-            `,
-            depthTest: true,
-            depthWrite: false,
-            transparent: false
-        });
-        // 恢复：把采样前保存的背景(tempMap)画回，避免洋红 quad 残留在屏幕
-        const material1b = new RawShaderMaterial({
-            uniforms: {
-                map: { value: tempMap },
-                scale: { value: null },
-                screenPosition: { value: null }
-            },
+            `,
+            depthTest: true,
+            depthWrite: false,
+            transparent: false
+        });
+        // 恢复：把采样前保存的背景(tempMap)画回，避免洋红 quad 残留在屏幕
+        const material1b = new RawShaderMaterial({
+            uniforms: {
+                map: { value: tempMap },
+                scale: { value: null },
+                screenPosition: { value: null }
+            },
             vertexShader: /* glsl */ `
                 precision highp float;
                 uniform vec3 screenPosition;
@@ -174,7 +174,7 @@ class BaseLensflare extends Mesh {
                     vUV = uv;
                     gl_Position = vec4( position.xy * scale + screenPosition.xy, screenPosition.z, 1.0 );
                 }
-            `,
+            `,
             fragmentShader: /* glsl */ `
                 precision highp float;
                 uniform sampler2D map;
@@ -182,192 +182,192 @@ class BaseLensflare extends Mesh {
                 void main() {
                     gl_FragColor = texture2D( map, vUV );
                 }
-            `,
-            depthTest: false,
-            depthWrite: false,
-            transparent: false
-        });
-        const elements = [];
-        // 鬼影元素材质（加色混合叠加到屏幕），含本项目新增的 occlusionForceVisible
-        const material2 = new RawShaderMaterial({
-            name: "LensflareElementShader",
-            uniforms: {
-                map: { value: null },
-                occlusionMap: { value: occlusionMap },
-                color: { value: new Color(0xffffff) },
-                scale: { value: new Vector2() },
-                screenPosition: { value: new Vector3() },
-                occlusionForceVisible: { value: 0.0 }
-            },
-            vertexShader: LensflareElementVertexShader,
-            fragmentShader: LensflareElementFragmentShader,
-            blending: AdditiveBlending,
-            transparent: true,
-            depthWrite: false
-        });
-        const mesh1 = new Mesh(geometry, material1a);
-        const mesh2 = new Mesh(geometry, material2);
-        // mesh2 用 screenPosition uniform 直接定位，不依赖真实 3D 位置；
-        // 关闭视锥剔除，避免 renderer.render 按 mesh2 世界坐标（默认原点）将其裁掉。
-        mesh2.frustumCulled = false;
-        // 独立的屏幕叠加场景：避免多实例共享场景导致 uniform 串扰，
-        // 同时保证 renderer.render 时内部 currentRenderState 被正确初始化。
-        const overlayScene = new Scene();
-        overlayScene.add(mesh2);
-        this.addElement = function (element) {
-            elements.push(element);
-        };
-        const scale = new Vector2();
-        const screenPositionPixels = new Vector2();
-        const validArea = new Box2();
-        const viewport = new Vector4();
-        // 本帧鬼影绘制所需的共享状态（onBeforeRender 计算、renderScreenOverlay 消费）
-        let frameCamera = null;
-        let frameVisible = false;
-        let frameForceVisible = 0.0;
-        let framePositionScreen = new Vector3();
-        let frameViewport = new Vector4();
-        // 屏幕叠加：由模块级 flushLensflareOverlays() 在渲染器输出屏幕后统一调用。
-        // 仅当本帧 onBeforeRender 计算出可见（光源在相机前方且在屏幕内/外但强制可见）时才画鬼影，
-        // 把鬼影串以加色混合叠加到当前屏幕帧缓冲（不污染任何中间后处理 target）。
-        // 必须用 renderer.render(scene, camera) 而不能用 renderBufferDirect：
-        // renderBufferDirect 依赖 renderer.render 流程建立的 currentRenderState，
-        // 终处理之后调用时 currentRenderState 已被清空，会出现 "null (reading 'state')" 崩溃。
-        this.renderScreenOverlay = function (renderer, camera) {
-            // 兜底：实例已从场景树移除（parent 为 null）时不绘制，
-            // 避免上层切页遗漏 dispose 时旧光晕残留在屏幕上。
-            if (!frameVisible || !frameCamera || this.parent === null)
-                return;
-            const vp = frameViewport;
-            const ps = framePositionScreen;
-            const vecX = -ps.x * 2;
-            const vecY = -ps.y * 2;
-            const sizeBbase = 1 / vp.w;
-            const invAspect2 = vp.w / vp.z;
-            for (let i = 0, l = elements.length; i < l; i++) {
-                const element = elements[i];
-                const u = material2.uniforms;
-                u.color.value.copy(element.color);
-                u.map.value = element.texture;
-                u.screenPosition.value.x = ps.x + vecX * element.distance;
-                u.screenPosition.value.y = ps.y + vecY * element.distance;
-                const sb = element.size * sizeBbase;
-                u.scale.value.set(sb * invAspect2, sb);
-                // 调试：强制鬼影完全可见，排除 occlusion/vVisibility 导致看不见的问题
-                u.occlusionForceVisible.value = 1.0;
-                material2.uniformsNeedUpdate = true;
-                renderer.render(overlayScene, frameCamera);
-            }
-        };
-        this.onBeforeRender = function (renderer, _scene, camera) {
-            renderer.getCurrentViewport(viewport);
-            const renderTarget = renderer.getRenderTarget();
-            const type = renderTarget !== null ? renderTarget.texture.type : UnsignedByteType;
-            if (currentType !== type) {
-                tempMap.dispose();
-                occlusionMap.dispose();
-                // three 类型定义把 Texture.type 标为 readonly，但运行时可写（需匹配 renderTarget 纹理类型）
-                tempMap.type = type;
-                occlusionMap.type = type;
-                currentType = type;
-            }
-            const invAspect = viewport.w / viewport.z;
-            const halfViewportWidth = viewport.z / 2.0;
-            const halfViewportHeight = viewport.w / 2.0;
-            const sizeA = 16 / viewport.w;
-            scale.set(sizeA * invAspect, sizeA);
-            validArea.min.set(viewport.x, viewport.y);
-            validArea.max.set(viewport.x + (viewport.z - 16), viewport.y + (viewport.w - 16));
-            // 计算光源在相机视图/屏幕空间的位置
-            positionView.setFromMatrixPosition(this.matrixWorld);
-            positionView.applyMatrix4(camera.matrixWorldInverse);
-            if (positionView.z > 0) {
-                // 光源在相机背后：不显示（几何无意义，非"超出屏幕"）
-                frameVisible = false;
-                return;
-            }
-            positionScreen.copy(positionView).applyMatrix4(camera.projectionMatrix);
-            // 光源像素坐标（遮挡采样 16x16 纹理居中在光源像素位置的 -8 处）
-            screenPositionPixels.x = viewport.x + (positionScreen.x * halfViewportWidth) + halfViewportWidth - 8;
-            screenPositionPixels.y = viewport.y + (positionScreen.y * halfViewportHeight) + halfViewportHeight - 8;
-            const onScreen = validArea.containsPoint(screenPositionPixels);
-            let forceVisible = 0.0;
-            if (onScreen) {
-                // 仅当光源在屏幕内才做遮挡采样（采样区域落到视口外会越界/得到无效遮挡图）
-                renderer.copyFramebufferToTexture(tempMap, screenPositionPixels);
-                let uniforms = material1a.uniforms;
-                uniforms.scale.value = scale;
-                uniforms.screenPosition.value = positionScreen;
-                renderer.renderBufferDirect(camera, null, geometry, material1a, mesh1, null);
-                renderer.copyFramebufferToTexture(occlusionMap, screenPositionPixels);
-                uniforms = material1b.uniforms;
-                uniforms.scale.value = scale;
-                uniforms.screenPosition.value = positionScreen;
-                renderer.renderBufferDirect(camera, null, geometry, material1b, mesh1, null);
-            }
-            else {
-                // 光源在屏幕外：遮挡采样越界无意义，强制鬼影可见（屏幕内的鬼影部分仍正常显示）
-                forceVisible = 1.0;
-            }
-            // 记录本帧状态，供 afterRender 在屏幕阶段绘制鬼影（已移除官方「光源在屏幕内才渲染」的整体 cull）。
-            // 超出屏幕的 quad 会在 afterRender 的 renderBufferDirect 时被 GPU 自动裁剪，落进屏幕内的鬼影照常显示。
-            frameCamera = camera;
-            frameVisible = true;
-            frameForceVisible = forceVisible;
-            framePositionScreen = positionScreen.clone();
-            frameViewport = viewport.clone();
-        };
-        this.dispose = function () {
-            lensflareInstances.delete(this);
-            material1a.dispose();
-            material1b.dispose();
-            material2.dispose();
-            tempMap.dispose();
-            occlusionMap.dispose();
-            for (let i = 0, l = elements.length; i < l; i++) {
-                elements[i].texture.dispose();
-            }
-        };
-    }
-}
-BaseLensflare.Geometry = (function () {
-    const geometry = new BufferGeometry();
-    const float32Array = new Float32Array([
-        -1, -1, 0, 0, 0,
-        1, -1, 0, 1, 0,
-        1, 1, 0, 1, 1,
-        -1, 1, 0, 0, 1
-    ]);
-    const interleavedBuffer = new InterleavedBuffer(float32Array, 5);
-    geometry.setIndex([0, 1, 2, 0, 2, 3]);
-    geometry.setAttribute("position", new InterleavedBufferAttribute(interleavedBuffer, 3, 0, false));
-    geometry.setAttribute("uv", new InterleavedBufferAttribute(interleavedBuffer, 2, 3, false));
-    return geometry;
-})();
-/** 对外暴露的镜头光晕组件：fork 自 three 的 Lensflare，已去除「光源出屏幕整串消失」的限制。 */
-export default class LensFlare extends BaseLensflare {
-    constructor(opts = {}) {
-        super();
-        const { color = "#ff9933", mainSize = 120, renderer } = opts;
-        if (renderer) {
-            this.ensureScreenOverlay(renderer);
-        }
-        const mainTex = textureLoader.load(customPNG);
-        // 主光点（光源正后方，尺寸最小，由 mainSize 控制；越小越不抢戏）
-        this.addElement(new LensflareElement(mainTex, mainSize, 0, new Color(color)));
-        // 正向鬼影：沿「光源→屏幕中心」连线分布，越靠近屏幕中心(distance 越大)尺寸越大
-        this.addElement(new LensflareElement(mainTex, 100, 0.6, new Color(color)));
-        this.addElement(new LensflareElement(mainTex, 140, 0.7, new Color(color)));
-        this.addElement(new LensflareElement(mainTex, 180, 0.9, new Color(color)));
-        this.addElement(new LensflareElement(mainTex, 220, 1, new Color(color)));
-        // 背面：光源后方，保持小尺寸
-        this.addElement(new LensflareElement(mainTex, 40, -0.2, new Color(color)));
-        this.addElement(new LensflareElement(mainTex, 70, -0.45, new Color(color)));
-        this.addElement(new LensflareElement(mainTex, 50, -0.7, new Color(color)));
-    }
-    /** 把光晕挂到某个光源（或任意 Object3D）上，使其出现在该对象的世界坐标处 */
-    attachTo(target) {
-        target.add(this);
-        return this;
-    }
-}
+            `,
+            depthTest: false,
+            depthWrite: false,
+            transparent: false
+        });
+        const elements = [];
+        // 鬼影元素材质（加色混合叠加到屏幕），含本项目新增的 occlusionForceVisible
+        const material2 = new RawShaderMaterial({
+            name: "LensflareElementShader",
+            uniforms: {
+                map: { value: null },
+                occlusionMap: { value: occlusionMap },
+                color: { value: new Color(0xffffff) },
+                scale: { value: new Vector2() },
+                screenPosition: { value: new Vector3() },
+                occlusionForceVisible: { value: 0.0 }
+            },
+            vertexShader: LensflareElementVertexShader,
+            fragmentShader: LensflareElementFragmentShader,
+            blending: AdditiveBlending,
+            transparent: true,
+            depthWrite: false
+        });
+        const mesh1 = new Mesh(geometry, material1a);
+        const mesh2 = new Mesh(geometry, material2);
+        // mesh2 用 screenPosition uniform 直接定位，不依赖真实 3D 位置；
+        // 关闭视锥剔除，避免 renderer.render 按 mesh2 世界坐标（默认原点）将其裁掉。
+        mesh2.frustumCulled = false;
+        // 独立的屏幕叠加场景：避免多实例共享场景导致 uniform 串扰，
+        // 同时保证 renderer.render 时内部 currentRenderState 被正确初始化。
+        const overlayScene = new Scene();
+        overlayScene.add(mesh2);
+        this.addElement = function (element) {
+            elements.push(element);
+        };
+        const scale = new Vector2();
+        const screenPositionPixels = new Vector2();
+        const validArea = new Box2();
+        const viewport = new Vector4();
+        // 本帧鬼影绘制所需的共享状态（onBeforeRender 计算、renderScreenOverlay 消费）
+        let frameCamera = null;
+        let frameVisible = false;
+        let frameForceVisible = 0.0;
+        let framePositionScreen = new Vector3();
+        let frameViewport = new Vector4();
+        // 屏幕叠加：由模块级 flushLensflareOverlays() 在渲染器输出屏幕后统一调用。
+        // 仅当本帧 onBeforeRender 计算出可见（光源在相机前方且在屏幕内/外但强制可见）时才画鬼影，
+        // 把鬼影串以加色混合叠加到当前屏幕帧缓冲（不污染任何中间后处理 target）。
+        // 必须用 renderer.render(scene, camera) 而不能用 renderBufferDirect：
+        // renderBufferDirect 依赖 renderer.render 流程建立的 currentRenderState，
+        // 终处理之后调用时 currentRenderState 已被清空，会出现 "null (reading 'state')" 崩溃。
+        this.renderScreenOverlay = function (renderer, camera) {
+            // 兜底：实例已从场景树移除（parent 为 null）时不绘制，
+            // 避免上层切页遗漏 dispose 时旧光晕残留在屏幕上。
+            if (!frameVisible || !frameCamera || this.parent === null)
+                return;
+            const vp = frameViewport;
+            const ps = framePositionScreen;
+            const vecX = -ps.x * 2;
+            const vecY = -ps.y * 2;
+            const sizeBbase = 1 / vp.w;
+            const invAspect2 = vp.w / vp.z;
+            for (let i = 0, l = elements.length; i < l; i++) {
+                const element = elements[i];
+                const u = material2.uniforms;
+                u.color.value.copy(element.color);
+                u.map.value = element.texture;
+                u.screenPosition.value.x = ps.x + vecX * element.distance;
+                u.screenPosition.value.y = ps.y + vecY * element.distance;
+                const sb = element.size * sizeBbase;
+                u.scale.value.set(sb * invAspect2, sb);
+                // 调试：强制鬼影完全可见，排除 occlusion/vVisibility 导致看不见的问题
+                u.occlusionForceVisible.value = 1.0;
+                material2.uniformsNeedUpdate = true;
+                renderer.render(overlayScene, frameCamera);
+            }
+        };
+        this.onBeforeRender = function (renderer, _scene, camera) {
+            renderer.getCurrentViewport(viewport);
+            const renderTarget = renderer.getRenderTarget();
+            const type = renderTarget !== null ? renderTarget.texture.type : UnsignedByteType;
+            if (currentType !== type) {
+                tempMap.dispose();
+                occlusionMap.dispose();
+                // three 类型定义把 Texture.type 标为 readonly，但运行时可写（需匹配 renderTarget 纹理类型）
+                tempMap.type = type;
+                occlusionMap.type = type;
+                currentType = type;
+            }
+            const invAspect = viewport.w / viewport.z;
+            const halfViewportWidth = viewport.z / 2.0;
+            const halfViewportHeight = viewport.w / 2.0;
+            const sizeA = 16 / viewport.w;
+            scale.set(sizeA * invAspect, sizeA);
+            validArea.min.set(viewport.x, viewport.y);
+            validArea.max.set(viewport.x + (viewport.z - 16), viewport.y + (viewport.w - 16));
+            // 计算光源在相机视图/屏幕空间的位置
+            positionView.setFromMatrixPosition(this.matrixWorld);
+            positionView.applyMatrix4(camera.matrixWorldInverse);
+            if (positionView.z > 0) {
+                // 光源在相机背后：不显示（几何无意义，非"超出屏幕"）
+                frameVisible = false;
+                return;
+            }
+            positionScreen.copy(positionView).applyMatrix4(camera.projectionMatrix);
+            // 光源像素坐标（遮挡采样 16x16 纹理居中在光源像素位置的 -8 处）
+            screenPositionPixels.x = viewport.x + (positionScreen.x * halfViewportWidth) + halfViewportWidth - 8;
+            screenPositionPixels.y = viewport.y + (positionScreen.y * halfViewportHeight) + halfViewportHeight - 8;
+            const onScreen = validArea.containsPoint(screenPositionPixels);
+            let forceVisible = 0.0;
+            if (onScreen) {
+                // 仅当光源在屏幕内才做遮挡采样（采样区域落到视口外会越界/得到无效遮挡图）
+                renderer.copyFramebufferToTexture(tempMap, screenPositionPixels);
+                let uniforms = material1a.uniforms;
+                uniforms.scale.value = scale;
+                uniforms.screenPosition.value = positionScreen;
+                renderer.renderBufferDirect(camera, null, geometry, material1a, mesh1, null);
+                renderer.copyFramebufferToTexture(occlusionMap, screenPositionPixels);
+                uniforms = material1b.uniforms;
+                uniforms.scale.value = scale;
+                uniforms.screenPosition.value = positionScreen;
+                renderer.renderBufferDirect(camera, null, geometry, material1b, mesh1, null);
+            }
+            else {
+                // 光源在屏幕外：遮挡采样越界无意义，强制鬼影可见（屏幕内的鬼影部分仍正常显示）
+                forceVisible = 1.0;
+            }
+            // 记录本帧状态，供 afterRender 在屏幕阶段绘制鬼影（已移除官方「光源在屏幕内才渲染」的整体 cull）。
+            // 超出屏幕的 quad 会在 afterRender 的 renderBufferDirect 时被 GPU 自动裁剪，落进屏幕内的鬼影照常显示。
+            frameCamera = camera;
+            frameVisible = true;
+            frameForceVisible = forceVisible;
+            framePositionScreen = positionScreen.clone();
+            frameViewport = viewport.clone();
+        };
+        this.dispose = function () {
+            lensflareInstances.delete(this);
+            material1a.dispose();
+            material1b.dispose();
+            material2.dispose();
+            tempMap.dispose();
+            occlusionMap.dispose();
+            for (let i = 0, l = elements.length; i < l; i++) {
+                elements[i].texture.dispose();
+            }
+        };
+    }
+}
+BaseLensflare.Geometry = (function () {
+    const geometry = new BufferGeometry();
+    const float32Array = new Float32Array([
+        -1, -1, 0, 0, 0,
+        1, -1, 0, 1, 0,
+        1, 1, 0, 1, 1,
+        -1, 1, 0, 0, 1
+    ]);
+    const interleavedBuffer = new InterleavedBuffer(float32Array, 5);
+    geometry.setIndex([0, 1, 2, 0, 2, 3]);
+    geometry.setAttribute("position", new InterleavedBufferAttribute(interleavedBuffer, 3, 0, false));
+    geometry.setAttribute("uv", new InterleavedBufferAttribute(interleavedBuffer, 2, 3, false));
+    return geometry;
+})();
+/** 对外暴露的镜头光晕组件：fork 自 three 的 Lensflare，已去除「光源出屏幕整串消失」的限制。 */
+export default class LensFlare extends BaseLensflare {
+    constructor(opts = {}) {
+        super();
+        const { color = "#ff9933", mainSize = 120, renderer } = opts;
+        if (renderer) {
+            this.ensureScreenOverlay(renderer);
+        }
+        const mainTex = textureLoader.load(customPNG);
+        // 主光点（光源正后方，尺寸最小，由 mainSize 控制；越小越不抢戏）
+        this.addElement(new LensflareElement(mainTex, mainSize, 0, new Color(color)));
+        // 正向鬼影：沿「光源→屏幕中心」连线分布，越靠近屏幕中心(distance 越大)尺寸越大
+        this.addElement(new LensflareElement(mainTex, 100, 0.6, new Color(color)));
+        this.addElement(new LensflareElement(mainTex, 140, 0.7, new Color(color)));
+        this.addElement(new LensflareElement(mainTex, 180, 0.9, new Color(color)));
+        this.addElement(new LensflareElement(mainTex, 220, 1, new Color(color)));
+        // 背面：光源后方，保持小尺寸
+        this.addElement(new LensflareElement(mainTex, 40, -0.2, new Color(color)));
+        this.addElement(new LensflareElement(mainTex, 70, -0.45, new Color(color)));
+        this.addElement(new LensflareElement(mainTex, 50, -0.7, new Color(color)));
+    }
+    /** 把光晕挂到某个光源（或任意 Object3D）上，使其出现在该对象的世界坐标处 */
+    attachTo(target) {
+        target.add(this);
+        return this;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-base",
-  "version": "2.0.142",
+  "version": "2.0.166",
   "description": "A Three.js extension library providing common 3D components, animations, materials, and utilities",
   "author": "xiaosihan",
   "publishConfig": {
@@ -27,6 +27,11 @@
     "./Transition": "./Transition.js",
     "./ThreeMouse": "./ThreeMouse.js",
     "./MeshBase": "./MeshBase.js",
+    "./MktMesh": {
+      "types": "./MktMesh/MktMesh.d.ts",
+      "import": "./MktMesh/MktMesh.js",
+      "require": "./MktMesh/MktMesh.js"
+    },
     "./InstancedMeshBase": "./instanced/InstancedMeshBase.js",
     "./threeLoader": "./threeLoader.js",
     "./threeUtils": "./threeUtils.js",

package/pass/bloom_pass.d.ts

@@ -1,2 +1,2 @@
-import { DepthTexture, WebGLRenderTarget, WebGLRenderer, Camera, Object3D } from "three";
-export default function bloom_pass(renderer: WebGLRenderer, camera: Camera, object3d: Object3D, baseRenderTarget: WebGLRenderTarget, baseDepthTexture: DepthTexture, devicePixelRatio: number): void;
+import { DepthTexture, WebGLRenderTarget, WebGLRenderer, Camera, Object3D } from "three";
+export default function bloom_pass(renderer: WebGLRenderer, camera: Camera, object3d: Object3D, baseRenderTarget: WebGLRenderTarget, baseDepthTexture: DepthTexture, devicePixelRatio: number): void;