three-base 2.0.188 → 2.0.190

package/ThreeBase.ts

@@ -113,22 +113,24 @@ export default class ThreeBase extends EventDispatcher<ThreeBaseEventTypeMap> {
     // （纹理被欠采样时的拍频，必须靠提高实际采样率才能消除）。
     // 1 = 关闭超采样（仅设备 pixelRatio）；2 = 2 倍超采样（质量最高，片元开销 ×4，需强 GPU）。
     renderScale: number = 1;
-    // 全局超采样/分辨率倍率（SSAA）：base / 深度 / 法线 / 效果 mask / 屏幕合成 全部按
-    // effectiveRatio × resolution 内部超采样渲染，终处理 FXAA 降采样输出到屏幕。
-    // 全链路同倍率 → 各 RT 严格 1:1 对齐：几何锯齿、效果边缘锯齿、辉光漏光（深度 vs mask 错位）、
-    // mask 合成 UV 缩放错位、SSAO 深度错位变黑 一并消除。
-    // ⭐ 现行 4（2026-10-27 用户点名「只把超采样倍率改成 4」，setter 的夹上限也是 4）：4 = 每维 4×、总像素 16×，
-    // 全链路填充与全部 RT 显存同比涨，卡顿风险由用户自测裁决。
-    // 上一档 1 出自 2026-10-21「有点卡，分辨率改成 1」；再早的默认 2 = 每维 2×、总像素 4×，
-    // 当时量过：35 张 RT 显存约 1.1 GB（1920×1080 画布）。1 那档几何硬边锯齿只由终处理 FXAA 兜底。
-    // 历史坑：baseRenderScale/auxRenderScale/effectRenderScale 三参各自为政，倍率不同步必错位，
-    // 故统一为单参数 resolution 管全局。
+    // 超采样倍率（SSAA）**只作用于 baseRenderTarget**（2026-10-27 需求：「只有 baseRT 的超采样参数是 4,
+    // 其他的 RT 超采样参数是 1」）：base 按 effectiveRatio × resolution 渲染，深度 / 法线 / 效果 mask /
+    // 屏幕合成一律按 effectiveRatio × auxResolution（= 1）渲染。
+    // ⚠️ 两条与「全链路同倍率」那版不同、看得见的后果：
+    //   ① base(4×) → screen(1×) 那次拷贝是**降采样**（RT 不长 mipmap，线性滤波只取到 4 个纹素）
+    //      ⇒ base 的超采样不会原样带到屏幕上，末端仍靠 FXAA 兜锯齿。
+    //   ② 描边/发光/覆盖/磨砂的 mask 与 base 深度都从 4× 降到 1×，而它们要合成进 4× 的 base
+    //      ⇒ 这些效果的边缘按 1× 精度放大，比同倍率那版软；UV 仍严格对齐（错位只发生在精度，不在位置）。
+    // 现行 resolution = 4（setter 夹的上限也是 4）；上一档 1 出自 2026-10-21「有点卡，分辨率改成 1」。
+    // 历史：再早是 base / 深度 / 法线 / mask / 屏幕 **共用同一个 resolution**，2026-10-27 起拆成 base 与其余两档。
 
-    // ⚠️ 必须用 getter/setter，不能是普通字段：所有 RT 尺寸只在 updateRenderTargetSizes()
-    // 里按 effectiveRatio × resolution 计算，而该方法过去只被 setSize()（容器尺寸变化）调用
+    // ⚠️ 必须用 getter/setter，不能是普通字段：RT 尺寸只在 updateRenderTargetSizes()
+    // 里按 effectiveRatio × resolution（base）/ × auxResolution（其余）计算，而该方法过去只被 setSize()（容器尺寸变化）调用
     // → 运行时改 resolution 不会重建任何 RT，画面毫无变化（表现为"调分辨率没感觉"）。
     // 故 setter 里改动倍率后立刻重建全部 RT。
     private _resolution: number = 4;
+    /** baseRenderTarget 之外**全部** RT 的倍率（深度 / 法线 / 各效果 mask / 屏幕合成）；1 = 不超采样 */
+    auxResolution: number = 1;
 
     get resolution(): number {
         return this._resolution;
@@ -232,6 +234,9 @@ export default class ThreeBase extends EventDispatcher<ThreeBaseEventTypeMap> {
         }
         const w = Math.max(1, Math.round(this.size.x * this.effectiveRatio * this._resolution));
         const h = Math.max(1, Math.round(this.size.y * this.effectiveRatio * this._resolution));
+        // 除 base 之外的 RT 走 auxResolution（= 1）：屏幕合成目标不跟着 base 超采样
+        const aw = Math.max(1, Math.round(this.size.x * this.effectiveRatio * this.auxResolution));
+        const ah = Math.max(1, Math.round(this.size.y * this.effectiveRatio * this.auxResolution));
         const opts = {
             minFilter: this._rtOptions.filter,
             magFilter: this._rtOptions.filter,
@@ -244,24 +249,23 @@ export default class ThreeBase extends EventDispatcher<ThreeBaseEventTypeMap> {
         this.baseRenderTarget = new WebGLRenderTarget(w, h, { ...opts });
         this.baseRenderTarget.texture.colorSpace = this._rtOptions.colorSpace;
         this.screenRenderTarget.dispose();
-        this.screenRenderTarget = new WebGLRenderTarget(w, h, { ...opts });
+        this.screenRenderTarget = new WebGLRenderTarget(aw, ah, { ...opts });
         this.screenRenderTarget.texture.colorSpace = this._rtOptions.colorSpace;
         this.needRender = true;
     }
 
-    // 效果 mask 像素比硬上限：避免高 dpr 屏（如 2×）上 effectiveRatio×resolution 爆到 4×，
-    // 让效果 mask RT（含辉光多次高斯迭代）填充量失控。经验值 2×：相对设备 dpr 输出足够平滑，
-    // 且把"效果 mask 超采样"的填充量控制在场景同级的 2× 以内（原本 3× 在高 dpr 屏是"还是卡"的高嫌疑点）。
+    // 效果 mask 像素比硬上限（历史旋钮，当前渲染链未再引用）：避免高 dpr 屏（如 2×）上
+    // effectiveRatio×resolution 爆到 4×，让效果 mask RT（含辉光多次高斯迭代）填充量失控。
+    // 2026-10-27 起 mask/深度/法线/屏幕全部按 auxResolution（= 1）走，超采样只留在 base 一张。
     effectMaxPixelRatio: number = 2;
-    // 超采样倍率已统一为上方 resolution 字段（base / 深度 / 法线 / mask / 屏幕全部取它）。
-    // 辅助通道（深度/法线）分辨率系数。
+    // 辅助通道（深度/法线）与各效果 mask、屏幕合成的倍率见下方 auxResolution 字段（= 1，不超采样）。
     // 关键：描边/发光/辉光/毛玻璃都拿 baseDepthTexture 做遮挡比对（deathTestShader 以全分辨率
     // UV 采样半分辨率深度，并与全分辨率物体深度做硬阈值比较）。半分辨率深度（Nearest 滤波）被
     // 放大采样后与锐利的物体深度在边缘逐像素翻转 discard，产生边缘摩尔纹/锯齿——这是这 4 个特效
-    // 共同的摩尔纹根因。故深度必须与 mask 同分辨率（全分辨率），1:1 采样才无放大错位。
-    // 法线仅 SSAO 使用（首页默认关闭、不渲染），全分辨率无额外开销。
-    // 之前为"不卡"降到 0.5 反而引入摩尔纹，已恢复为 1。
-    // 辅助通道(深度/法线)倍率已并入 resolution，不再单独设 auxRenderScale。
+    // 共同的摩尔纹根因。故深度与 mask 必须同倍率（都取 auxResolution），彼此 1:1 采样才无放大错位。
+    // 法线仅 SSAO 使用（首页默认关闭、不渲染），无额外开销。
+    // 之前为"不卡"把深度单独降到 0.5 反而引入摩尔纹，已恢复为 1。
+    // 辅助通道(深度/法线)倍率 = auxResolution，与 base 的 resolution 分离（2026-10-27 需求）。
     // 实际帧缓冲像素比 = min( max(devicePixelRatio, minDevicePixelRatio) * renderScale, maxPixelRatio )
     get effectiveRatio(): number {
         return Math.min(Math.max(window.devicePixelRatio, this.minDevicePixelRatio) * this.renderScale, this.maxPixelRatio);
@@ -552,7 +556,8 @@ export default class ThreeBase extends EventDispatcher<ThreeBaseEventTypeMap> {
         this.orthographicCamera.right = width / height;
         this.renderer.setPixelRatio(Math.max(window.devicePixelRatio, this.minDevicePixelRatio)),
             this.renderer.setSize(width, height);
-        // 所有 RT 尺寸按 effectiveRatio × resolution 重建（容器尺寸变化与 resolution 变化共用）
+        // base 按 effectiveRatio × resolution、其余 RT 按 effectiveRatio × auxResolution 重建
+        // （容器尺寸变化与 resolution 变化共用）
         this.updateRenderTargetSizes(width, height);
         this.size.set(width, height);
         setTimeout(() => {
@@ -564,7 +569,8 @@ export default class ThreeBase extends EventDispatcher<ThreeBaseEventTypeMap> {
     }
 
     /**
-     * 按「容器尺寸 × effectiveRatio × resolution」重建所有渲染目标尺寸。
+     * 按「容器尺寸 × effectiveRatio」重建所有渲染目标尺寸：base 再乘 resolution，
+     * 其余（深度 / 法线 / mask / 屏幕合成）再乘 auxResolution。
      * 由 setSize()（容器尺寸变化）与 resolution setter（运行时调倍率）共用 ——
      * 关键：resolution 是运行时可调的性能/质量旋钮，改完必须立刻重建 RT，
      * 否则倍率变了而 RT 尺寸没变，画面毫无变化（历史坑："调分辨率没感觉"）。
@@ -573,18 +579,21 @@ export default class ThreeBase extends EventDispatcher<ThreeBaseEventTypeMap> {
         // 防御 0 尺寸：RT 不接受 0，否则 WebGL 报 framebuffer incomplete
         const w = Math.max(1, Math.round(width * this.effectiveRatio * this._resolution));
         const h = Math.max(1, Math.round(height * this.effectiveRatio * this._resolution));
+        const aw = Math.max(1, Math.round(width * this.effectiveRatio * this.auxResolution));
+        const ah = Math.max(1, Math.round(height * this.effectiveRatio * this.auxResolution));
 
-        // 主画面：超采样渲染，纹理摩尔纹在此被根治
+        // 主画面：只有这一张吃 resolution 超采样（纹理摩尔纹在此被根治）
         this.baseRenderTarget.setSize(w, h);
-        // 深度/法线辅助通道：与 base 同倍率，保证 depthTest 1:1 无漏光、SSAO 深度不黑。
+        // 深度/法线辅助通道：按 auxResolution（= 1）。与 base 之间**倍率不同但 UV 一致**，
+        // 遮挡判定读的是归一化 UV ⇒ 位置不错位，只是精度按 1× 走（2026-10-27 需求点名要的这一档）。
         // 其 depthTexture(baseDepthTexture) 尺寸由 renderer 在 setRenderTarget 时
         // 强制同步为 depthRenderTarget 尺寸，下面再手动对齐一次避免首帧抖动。
-        this.depthRenderTarget.setSize(w, h);
-        this.normalRenderTarget.setSize(w, h);
-        // 屏幕合成目标：同样跟随 resolution，全链路 1:1 对齐
-        this.screenRenderTarget.setSize(w, h);
-        this.baseDepthTexture.image.width = w;
-        this.baseDepthTexture.image.height = h;
+        this.depthRenderTarget.setSize(aw, ah);
+        this.normalRenderTarget.setSize(aw, ah);
+        // 屏幕合成目标：同样按 auxResolution，与 base 之间的那次拷贝是降采样
+        this.screenRenderTarget.setSize(aw, ah);
+        this.baseDepthTexture.image.width = aw;
+        this.baseDepthTexture.image.height = ah;
         // 立即渲染一帧，避免静态场景下改了倍率却停在旧画面
         this.needRender = true;
     }
@@ -997,10 +1006,10 @@ export default class ThreeBase extends EventDispatcher<ThreeBaseEventTypeMap> {
             renderVisibleDepthPass(this.renderer, camera, this.scene, this.depthRenderTarget);
             // 切回 baseRenderTarget，后处理 pass 需要把效果叠加到颜色渲染目标上
             this.renderer.setRenderTarget(this.baseRenderTarget);
-            // 效果 mask 灰度图尺寸 = effectiveRatio × resolution，与 baseRenderTarget / baseDepthTexture 同倍率，
-            // 全链路 1:1 对齐（mask 跟随 resolution，深度也跟随 resolution，辉光漏光/mask 合成 UV 错位均消除）。
-            // 几何/效果边缘抗锯齿由「baseRenderTarget/screenRenderTarget 超采样(resolution) + 终处理 FXAA 降采样」承担。
-            const dpr = this.effectiveRatio * this.resolution;
+            // 效果 mask 灰度图尺寸 = effectiveRatio × auxResolution（= 1），与 baseDepthTexture 同倍率；
+            // baseRenderTarget 是唯一的超采样档（resolution），故 mask/深度 → base 的合成是「1× 精度放大到 4×」。
+            // 位置靠归一化 UV 对齐，不会偏移；只是描边/发光/覆盖/磨砂的边缘精度按 1× 走（2026-10-27 需求）。
+            const dpr = this.effectiveRatio * this.auxResolution;
             // SSAO 后处理（基于深度计算遮蔽，乘法叠加）：数据准备 + 计算全在 ssao_pass 内部，
             // 结果输出到「调用时绑定的渲染目标」。
             // ⚠️ 顺序（2026-09-14 皇上旨）：SSAO 必须排在对象级特效（描边/发光/bloom/覆盖/磨砂）之前——
@@ -1011,18 +1020,18 @@ export default class ThreeBase extends EventDispatcher<ThreeBaseEventTypeMap> {
             // 后处理特效渲染(描边,发光,颜色覆盖,bloom,磨砂玻璃)：叠加到 baseRenderTarget（此时已含 SSAO）
             this.scene.traverseVisible((child: Object3D) => {
                 if (child instanceof Mesh || child instanceof Line || child instanceof Points) {
-                    stroke_pass(this.renderer, camera, child, this.baseDepthTexture, this.effectiveRatio * this.resolution);
-                    glow_pass(this.renderer, camera, child, this.baseDepthTexture, this.effectiveRatio * this.resolution);
-                    bloom_pass(this.renderer, camera, child, this.baseRenderTarget, this.baseDepthTexture, this.effectiveRatio * this.resolution);
+                    stroke_pass(this.renderer, camera, child, this.baseDepthTexture, dpr);
+                    glow_pass(this.renderer, camera, child, this.baseDepthTexture, dpr);
+                    bloom_pass(this.renderer, camera, child, this.baseRenderTarget, this.baseDepthTexture, dpr);
                 }
             });
             // 自定义描边对象（如 InstancedChild 的选择代理）：不在 scene 内，单独在效果阶段描边。
             // 代理用实例自身的 matrixWorld + 同款 geometry/material 重建，故其深度/灰度与真实实例严格对齐，
             // 并复用同一张 baseDepthTexture 做遮挡判定（被其他物体挡住的部分不描边）。
             for (const so of this._strokeObjects) {
-                stroke_pass(this.renderer, camera, so, this.baseDepthTexture, this.effectiveRatio * this.resolution);
-                glow_pass(this.renderer, camera, so, this.baseDepthTexture, this.effectiveRatio * this.resolution);
-                bloom_pass(this.renderer, camera, so, this.baseRenderTarget, this.baseDepthTexture, this.effectiveRatio * this.resolution);
+                stroke_pass(this.renderer, camera, so, this.baseDepthTexture, dpr);
+                glow_pass(this.renderer, camera, so, this.baseDepthTexture, dpr);
+                bloom_pass(this.renderer, camera, so, this.baseRenderTarget, this.baseDepthTexture, dpr);
             }
             // 把 base(含 SSAO)+描边/发光/bloom 合成结果拷到屏幕合成目标，后续 颜色叠加/磨砂玻璃
             // 在此目标上叠加；最后统一跑一次 FXAA 终处理输出到屏幕，覆盖全部后处理的锯齿/摩尔纹。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "three-base",
-  "version": "2.0.188",
+  "version": "2.0.190",
   "description": "A Three.js extension library providing common 3D components, animations, materials, and utilities",
   "author": "xiaosihan",
   "publishConfig": {