three-base 2.0.137 → 2.0.142

package/shaders/FXAAShaderMaterial.js

@@ -1,16 +1,15 @@
-/*
- * @Author: xiaosihan
- * @Date: 2024-01-20 05:10:37
- * @Last Modified by: xiaosihan
- * @Last Modified time: 2024-01-20 05:10:57
- */
-import { NoBlending, ShaderChunk, ShaderMaterial, Vector2 } from "three";
-// 抗锯齿着色器
-const FXAAShaderMaterial = new ShaderMaterial({
-    uniforms: {
-        tDiffuse: { value: null }, // 贴图纹理
-        resolution: { value: new Vector2(1 / 1024, 1 / 1024) }
-    },
+/*
+ * @Author: xiaosihan
+ * @Date: 2024-01-20 05:10:37
+ * @Last Modified by: xiaosihan
+ * @Last Modified time: 2024-01-20 05:10:57
+ */
+import { NoBlending, ShaderChunk, ShaderMaterial, Vector2 } from "three";
+const FXAAShaderMaterial = new ShaderMaterial({
+    uniforms: {
+        tDiffuse: { value: null },
+        resolution: { value: new Vector2(1 / 1024, 1 / 1024) }
+    },
     vertexShader: `
         ${ShaderChunk.common}
         ${ShaderChunk.logdepthbuf_pars_vertex}
@@ -20,7 +19,7 @@ const FXAAShaderMaterial = new ShaderMaterial({
             gl_Position = projectionMatrix * modelViewMatrix * vec4( position, 1.0 );
             ${ShaderChunk.logdepthbuf_vertex}
         }
-    `,
+    `,
     fragmentShader: `
         ${ShaderChunk.logdepthbuf_pars_fragment}
         precision highp float;
@@ -32,14 +31,6 @@ const FXAAShaderMaterial = new ShaderMaterial({
         varying vec2 vUv;
     
         #ifndef FXAA_DISCARD
-                //
-                // Only valid for PC OpenGL currently.
-                // Probably will not work when FXAA_GREEN_AS_LUMA = 1.
-                //
-                // 1 = Use discard on pixels which don't need AA.
-                //     For APIs which enable concurrent TEX+ROP from same surface.
-                // 0 = Return unchanged color on pixels which don't need AA.
-                //
                 #define FXAA_DISCARD 0
         #endif
     
@@ -50,7 +41,6 @@ const FXAAShaderMaterial = new ShaderMaterial({
     
         #define NUM_SAMPLES 5
     
-        // assumes colors have premultipliedAlpha, so that the calculated color contrast is scaled by alpha
         float contrast( vec4 a, vec4 b ) {
                 vec4 diff = abs( a - b );
                 return max( max( max( diff.r, diff.g ), diff.b ), diff.a );
@@ -75,9 +65,6 @@ const FXAAShaderMaterial = new ShaderMaterial({
                 vec4 rgbaE = FxaaTexOff(tex, posM, vec2( 1.0, 0.0), fxaaQualityRcpFrame.xy);
                 vec4 rgbaN = FxaaTexOff(tex, posM, vec2( 0.0,-1.0), fxaaQualityRcpFrame.xy);
                 vec4 rgbaW = FxaaTexOff(tex, posM, vec2(-1.0, 0.0), fxaaQualityRcpFrame.xy);
-                // . S .
-                // W M E
-                // . N .
     
                 bool earlyExit = max( max( max(
                         contrast( rgbaM, rgbaN ),
@@ -85,9 +72,6 @@ const FXAAShaderMaterial = new ShaderMaterial({
                         contrast( rgbaM, rgbaE ) ),
                         contrast( rgbaM, rgbaW ) )
                         < fxaaQualityEdgeThreshold;
-                // . 0 .
-                // 0 0 0
-                // . 0 .
     
                 #if (FXAA_DISCARD == 1)
                         if(earlyExit) FxaaDiscard;
@@ -104,44 +88,22 @@ const FXAAShaderMaterial = new ShaderMaterial({
                 relativeVContrast *= fxaaQualityinvEdgeThreshold;
     
                 bool horzSpan = relativeVContrast > 0.;
-                // . 1 .
-                // 0 0 0
-                // . 1 .
     
-                // 45 deg edge detection and corners of objects, aka V/H contrast is too similar
                 if( abs( relativeVContrast ) < .3 ) {
-                        // locate the edge
                         vec2 dirToEdge;
                         dirToEdge.x = contrastE > contrastW ? 1. : -1.;
                         dirToEdge.y = contrastS > contrastN ? 1. : -1.;
-                        // . 2 .      . 1 .
-                        // 1 0 2  ~=  0 0 1
-                        // . 1 .      . 0 .
-    
-                        // tap 2 pixels and see which ones are "outside" the edge, to
-                        // determine if the edge is vertical or horizontal
     
                         vec4 rgbaAlongH = FxaaTexOff(tex, posM, vec2( dirToEdge.x, -dirToEdge.y ), fxaaQualityRcpFrame.xy);
                         float matchAlongH = contrast( rgbaM, rgbaAlongH );
-                        // . 1 .
-                        // 0 0 1
-                        // . 0 H
     
                         vec4 rgbaAlongV = FxaaTexOff(tex, posM, vec2( -dirToEdge.x, dirToEdge.y ), fxaaQualityRcpFrame.xy);
                         float matchAlongV = contrast( rgbaM, rgbaAlongV );
-                        // V 1 .
-                        // 0 0 1
-                        // . 0 .
     
                         relativeVContrast = matchAlongV - matchAlongH;
                         relativeVContrast *= fxaaQualityinvEdgeThreshold;
     
-                        if( abs( relativeVContrast ) < .3 ) { // 45 deg edge
-                                // 1 1 .
-                                // 0 0 1
-                                // . 0 1
-    
-                                // do a simple blur
+                        if( abs( relativeVContrast ) < .3 ) {
                                 return mix(
                                         rgbaM,
                                         (rgbaN + rgbaS + rgbaE + rgbaW) * .25,
@@ -154,9 +116,6 @@ const FXAAShaderMaterial = new ShaderMaterial({
     
                 if(!horzSpan) rgbaN = rgbaW;
                 if(!horzSpan) rgbaS = rgbaE;
-                // . 0 .      1
-                // 1 0 1  ->  0
-                // . 0 .      1
     
                 bool pairN = contrast( rgbaM, rgbaN ) > contrast( rgbaM, rgbaS );
                 if(!pairN) rgbaN = rgbaS;
@@ -202,15 +161,13 @@ const FXAAShaderMaterial = new ShaderMaterial({
                 }
     
     
-                if ( !doneP && !doneN ) return rgbaM; // failed to find end of edge
+                if ( !doneP && !doneN ) return rgbaM;
     
                 float dist = min(
                         doneN ? float( iterationsUsedN ) / float( NUM_SAMPLES - 1 ) : 1.,
                         doneP ? float( iterationsUsedP ) / float( NUM_SAMPLES - 1 ) : 1.
                 );
     
-                // hacky way of reduces blurriness of mostly diagonal edges
-                // but reduces AA quality
                 dist = pow(dist, .5);
     
                 dist = 1. - dist;
@@ -230,15 +187,15 @@ const FXAAShaderMaterial = new ShaderMaterial({
                         vUv,
                         tDiffuse,
                         resolution,
-                        edgeDetectionQuality, // [0,1] contrast needed, otherwise early discard
+                        edgeDetectionQuality,
                         invEdgeDetectionQuality
                 );
             ${ShaderChunk.logdepthbuf_fragment}
         }
-    `,
-    blending: NoBlending, // 渲染时不与背景融合计算 直接替换
-    depthTest: false,
-    depthWrite: false,
-    transparent: true
-});
-export default FXAAShaderMaterial;
+    `,
+    blending: NoBlending,
+    depthTest: false,
+    depthWrite: false,
+    transparent: true
+});
+export default FXAAShaderMaterial;

package/shaders/FXAAShaderMaterial.ts

@@ -0,0 +1,201 @@
+/*
+ * @Author: xiaosihan
+ * @Date: 2024-01-20 05:10:37
+ * @Last Modified by: xiaosihan
+ * @Last Modified time: 2024-01-20 05:10:57
+ */
+import { NoBlending, ShaderChunk, ShaderMaterial, Vector2 } from "three";
+const FXAAShaderMaterial = new ShaderMaterial({
+    uniforms: {
+        tDiffuse: { value: null },
+        resolution: { value: new Vector2(1 / 1024, 1 / 1024) }
+    },
+    vertexShader: `
+        ${ShaderChunk.common}
+        ${ShaderChunk.logdepthbuf_pars_vertex}
+        varying vec2 vUv;
+        void main() {
+            vUv = uv;
+            gl_Position = projectionMatrix * modelViewMatrix * vec4( position, 1.0 );
+            ${ShaderChunk.logdepthbuf_vertex}
+        }
+    `,
+    fragmentShader: `
+        ${ShaderChunk.logdepthbuf_pars_fragment}
+        precision highp float;
+
+        uniform sampler2D tDiffuse;
+    
+        uniform vec2 resolution;
+    
+        varying vec2 vUv;
+    
+        #ifndef FXAA_DISCARD
+                #define FXAA_DISCARD 0
+        #endif
+    
+        /*--------------------------------------------------------------------------*/
+        #define FxaaTexTop(t, p) texture2D(t, p, -100.0)
+        #define FxaaTexOff(t, p, o, r) texture2D(t, p + (o * r), -100.0)
+        /*--------------------------------------------------------------------------*/
+    
+        #define NUM_SAMPLES 5
+    
+        float contrast( vec4 a, vec4 b ) {
+                vec4 diff = abs( a - b );
+                return max( max( max( diff.r, diff.g ), diff.b ), diff.a );
+        }
+    
+        /*============================================================================
+    
+                                        FXAA3 QUALITY - PC
+    
+        ============================================================================*/
+    
+        /*--------------------------------------------------------------------------*/
+        vec4 FxaaPixelShader(
+                vec2 posM,
+                sampler2D tex,
+                vec2 fxaaQualityRcpFrame,
+                float fxaaQualityEdgeThreshold,
+                float fxaaQualityinvEdgeThreshold
+        ) {
+                vec4 rgbaM = FxaaTexTop(tex, posM);
+                vec4 rgbaS = FxaaTexOff(tex, posM, vec2( 0.0, 1.0), fxaaQualityRcpFrame.xy);
+                vec4 rgbaE = FxaaTexOff(tex, posM, vec2( 1.0, 0.0), fxaaQualityRcpFrame.xy);
+                vec4 rgbaN = FxaaTexOff(tex, posM, vec2( 0.0,-1.0), fxaaQualityRcpFrame.xy);
+                vec4 rgbaW = FxaaTexOff(tex, posM, vec2(-1.0, 0.0), fxaaQualityRcpFrame.xy);
+    
+                bool earlyExit = max( max( max(
+                        contrast( rgbaM, rgbaN ),
+                        contrast( rgbaM, rgbaS ) ),
+                        contrast( rgbaM, rgbaE ) ),
+                        contrast( rgbaM, rgbaW ) )
+                        < fxaaQualityEdgeThreshold;
+    
+                #if (FXAA_DISCARD == 1)
+                        if(earlyExit) FxaaDiscard;
+                #else
+                        if(earlyExit) return rgbaM;
+                #endif
+    
+                float contrastN = contrast( rgbaM, rgbaN );
+                float contrastS = contrast( rgbaM, rgbaS );
+                float contrastE = contrast( rgbaM, rgbaE );
+                float contrastW = contrast( rgbaM, rgbaW );
+    
+                float relativeVContrast = ( contrastN + contrastS ) - ( contrastE + contrastW );
+                relativeVContrast *= fxaaQualityinvEdgeThreshold;
+    
+                bool horzSpan = relativeVContrast > 0.;
+    
+                if( abs( relativeVContrast ) < .3 ) {
+                        vec2 dirToEdge;
+                        dirToEdge.x = contrastE > contrastW ? 1. : -1.;
+                        dirToEdge.y = contrastS > contrastN ? 1. : -1.;
+    
+                        vec4 rgbaAlongH = FxaaTexOff(tex, posM, vec2( dirToEdge.x, -dirToEdge.y ), fxaaQualityRcpFrame.xy);
+                        float matchAlongH = contrast( rgbaM, rgbaAlongH );
+    
+                        vec4 rgbaAlongV = FxaaTexOff(tex, posM, vec2( -dirToEdge.x, dirToEdge.y ), fxaaQualityRcpFrame.xy);
+                        float matchAlongV = contrast( rgbaM, rgbaAlongV );
+    
+                        relativeVContrast = matchAlongV - matchAlongH;
+                        relativeVContrast *= fxaaQualityinvEdgeThreshold;
+    
+                        if( abs( relativeVContrast ) < .3 ) {
+                                return mix(
+                                        rgbaM,
+                                        (rgbaN + rgbaS + rgbaE + rgbaW) * .25,
+                                        .4
+                                );
+                        }
+    
+                        horzSpan = relativeVContrast > 0.;
+                }
+    
+                if(!horzSpan) rgbaN = rgbaW;
+                if(!horzSpan) rgbaS = rgbaE;
+    
+                bool pairN = contrast( rgbaM, rgbaN ) > contrast( rgbaM, rgbaS );
+                if(!pairN) rgbaN = rgbaS;
+    
+                vec2 offNP;
+                offNP.x = (!horzSpan) ? 0.0 : fxaaQualityRcpFrame.x;
+                offNP.y = ( horzSpan) ? 0.0 : fxaaQualityRcpFrame.y;
+    
+                bool doneN = false;
+                bool doneP = false;
+    
+                float nDist = 0.;
+                float pDist = 0.;
+    
+                vec2 posN = posM;
+                vec2 posP = posM;
+    
+                int iterationsUsed = 0;
+                int iterationsUsedN = 0;
+                int iterationsUsedP = 0;
+                for( int i = 0; i < NUM_SAMPLES; i++ ) {
+                        iterationsUsed = i;
+    
+                        float increment = float(i + 1);
+    
+                        if(!doneN) {
+                                nDist += increment;
+                                posN = posM + offNP * nDist;
+                                vec4 rgbaEndN = FxaaTexTop(tex, posN.xy);
+                                doneN = contrast( rgbaEndN, rgbaM ) > contrast( rgbaEndN, rgbaN );
+                                iterationsUsedN = i;
+                        }
+    
+                        if(!doneP) {
+                                pDist += increment;
+                                posP = posM - offNP * pDist;
+                                vec4 rgbaEndP = FxaaTexTop(tex, posP.xy);
+                                doneP = contrast( rgbaEndP, rgbaM ) > contrast( rgbaEndP, rgbaN );
+                                iterationsUsedP = i;
+                        }
+    
+                        if(doneN || doneP) break;
+                }
+    
+    
+                if ( !doneP && !doneN ) return rgbaM;
+    
+                float dist = min(
+                        doneN ? float( iterationsUsedN ) / float( NUM_SAMPLES - 1 ) : 1.,
+                        doneP ? float( iterationsUsedP ) / float( NUM_SAMPLES - 1 ) : 1.
+                );
+    
+                dist = pow(dist, .5);
+    
+                dist = 1. - dist;
+    
+                return mix(
+                        rgbaM,
+                        rgbaN,
+                        dist * .5
+                );
+        }
+    
+        void main() {
+                const float edgeDetectionQuality = .2;
+                const float invEdgeDetectionQuality = 1. / edgeDetectionQuality;
+    
+                gl_FragColor = FxaaPixelShader(
+                        vUv,
+                        tDiffuse,
+                        resolution,
+                        edgeDetectionQuality,
+                        invEdgeDetectionQuality
+                );
+            ${ShaderChunk.logdepthbuf_fragment}
+        }
+    `,
+    blending: NoBlending,
+    depthTest: false,
+    depthWrite: false,
+    transparent: true
+});
+export default FXAAShaderMaterial;

package/shaders/baseDepthVisShader.d.ts

@@ -0,0 +1,11 @@
+import { ShaderMaterial } from "three";
+/**
+ * 调试用：把 baseDepthTexture（可见深度图）直接以灰度输出到屏幕。
+ * 对数深度：近=0(黑) 远=1(白)。
+ *   - 全屏纯白  → 深度图为空（全 clear 1.0），说明 renderAoDepthPass 没把深度写进 baseDepthTexture；
+ *                 此时所有依赖深度遮挡的后处理(stroke/glow/cover/frosted)都会"一律显示在前"。
+ *   - 有灰阶/明暗  → 深度图正常，问题在比对侧(selectDepth / depthTestShader)。
+ * 触发：在控制台执行 `window.__BASE_DEPTH_VIS = true` 后画面即切到该视图。
+ */
+declare const baseDepthVisShader: ShaderMaterial;
+export default baseDepthVisShader;

package/shaders/baseDepthVisShader.js

@@ -0,0 +1,36 @@
+import { ShaderChunk, ShaderMaterial } from "three";
+/**
+ * 调试用：把 baseDepthTexture（可见深度图）直接以灰度输出到屏幕。
+ * 对数深度：近=0(黑) 远=1(白)。
+ *   - 全屏纯白  → 深度图为空（全 clear 1.0），说明 renderAoDepthPass 没把深度写进 baseDepthTexture；
+ *                 此时所有依赖深度遮挡的后处理(stroke/glow/cover/frosted)都会"一律显示在前"。
+ *   - 有灰阶/明暗  → 深度图正常，问题在比对侧(selectDepth / depthTestShader)。
+ * 触发：在控制台执行 `window.__BASE_DEPTH_VIS = true` 后画面即切到该视图。
+ */
+const baseDepthVisShader = new ShaderMaterial({
+    uniforms: {
+        tDepth: { value: null },
+    },
+    vertexShader: `
+        ${ShaderChunk.common}
+        ${ShaderChunk.logdepthbuf_pars_vertex}
+        varying vec2 vUv;
+        void main() {
+            vUv = uv;
+            gl_Position = projectionMatrix * modelViewMatrix * vec4( position, 1.0 );
+            ${ShaderChunk.logdepthbuf_vertex}
+        }
+    `,
+    fragmentShader: `
+        uniform sampler2D tDepth;
+        varying vec2 vUv;
+        void main() {
+            float d = texture2D(tDepth, vUv).r;
+            gl_FragColor = vec4(d, d, d, 1.0);
+        }
+    `,
+    depthTest: false,
+    depthWrite: false,
+    transparent: true,
+});
+export default baseDepthVisShader;

package/shaders/baseDepthVisShader.ts

@@ -0,0 +1,36 @@
+import { ShaderChunk, ShaderMaterial } from "three";
+/**
+ * 调试用：把 baseDepthTexture（可见深度图）直接以灰度输出到屏幕。
+ * 对数深度：近=0(黑) 远=1(白)。
+ *   - 全屏纯白  → 深度图为空（全 clear 1.0），说明 renderAoDepthPass 没把深度写进 baseDepthTexture；
+ *                 此时所有依赖深度遮挡的后处理(stroke/glow/cover/frosted)都会"一律显示在前"。
+ *   - 有灰阶/明暗  → 深度图正常，问题在比对侧(selectDepth / depthTestShader)。
+ * 触发：在控制台执行 `window.__BASE_DEPTH_VIS = true` 后画面即切到该视图。
+ */
+const baseDepthVisShader = new ShaderMaterial({
+    uniforms: {
+        tDepth: { value: null as unknown as import("three").Texture },
+    },
+    vertexShader: `
+        ${ShaderChunk.common}
+        ${ShaderChunk.logdepthbuf_pars_vertex}
+        varying vec2 vUv;
+        void main() {
+            vUv = uv;
+            gl_Position = projectionMatrix * modelViewMatrix * vec4( position, 1.0 );
+            ${ShaderChunk.logdepthbuf_vertex}
+        }
+    `,
+    fragmentShader: `
+        uniform sampler2D tDepth;
+        varying vec2 vUv;
+        void main() {
+            float d = texture2D(tDepth, vUv).r;
+            gl_FragColor = vec4(d, d, d, 1.0);
+        }
+    `,
+    depthTest: false,
+    depthWrite: false,
+    transparent: true,
+});
+export default baseDepthVisShader;

package/shaders/baseTextureToRenderShader.d.ts

@@ -1,2 +1,2 @@
-import { ShaderMaterial } from "three";
-export declare const baseTextureToRenderShader: ShaderMaterial;
+import { ShaderMaterial } from "three";
+export declare const baseTextureToRenderShader: ShaderMaterial;

package/shaders/baseTextureToRenderShader.js

@@ -1,10 +1,11 @@
-import { ShaderMaterial, Vector2, ShaderChunk, NoBlending } from "three";
-// 渲染目标绘制到渲染器着色器
-export const baseTextureToRenderShader = new ShaderMaterial({
-    uniforms: {
-        tDiffuse: { value: null }, // 贴图纹理
-        resolution: { value: new Vector2(1 / 1024, 1 / 1024) }
-    },
+import { ShaderMaterial, Vector2, ShaderChunk, NoBlending } from "three";
+export const baseTextureToRenderShader = new ShaderMaterial({
+    uniforms: {
+        tDiffuse: { value: null },
+        resolution: { value: new Vector2(1 / 1024, 1 / 1024) },
+        /** 抖动强度：1.0 = 标准 ±0.5 LSB（总跨度 1/255），0 = 关闭（A/B 对比用） */
+        uDitherStrength: { value: 1.0 }
+    },
     vertexShader: `
         ${ShaderChunk.common}
         ${ShaderChunk.logdepthbuf_pars_vertex}
@@ -14,7 +15,7 @@ export const baseTextureToRenderShader = new ShaderMaterial({
             gl_Position = projectionMatrix * modelViewMatrix * vec4( position, 1.0 );
             ${ShaderChunk.logdepthbuf_vertex}
         }
-    `,
+    `,
     fragmentShader: `
         ${ShaderChunk.logdepthbuf_pars_fragment}
         precision highp float;
@@ -23,17 +24,30 @@ export const baseTextureToRenderShader = new ShaderMaterial({
     
         uniform vec2 resolution;
     
+        /** 抖动强度（1.0 = ±0.5 LSB；0 = 关闭） */
+        uniform float uDitherStrength;
+    
         varying vec2 vUv;
     
+        /**
+         * 交错梯度噪声 Interleaved Gradient Noise，返回 [0,1)。
+         *
+         * 为什么不用 Bayer 有序矩阵（2026-09-06 皇上反馈「辉光透明度不对」后改）：
+         *   Bayer 是 8×8 块状循环图案，在大面积柔和渐变（外辉光/天空/雾）上会形成**肉眼可见的规则
+         *   网格/点阵**，把自然的透明度渐变打成"脏"的质感；辉光暗部（R 仅 16~47）一个码值就是
+         *   2%~6% 跳变，网格尤其明显。IGN 是高频交错梯度，没有块状结构，人眼几乎察觉不到。
+         *
+         * 为什么不用 sin()/大数 fract() 版哈希（如 hash12）：它依赖 fract(4531.99) 这类大数的
+         *   小数位精度，在不同 GPU / 驱动 / 精度限定符（mediump vs highp）下行为不一致，
+         *   存在退化成常数的风险（一旦退化，抖动就变成恒定偏移，色带一根没少）。
+         *   IGN 内部最大值约 52.98，精度安全边际大得多。
+         * ⚠️ 澄清：Bayer 被替换**不是**因为精度（实测大坐标下不退化），纯粹是块状网格的观感问题。
+         */
+        float ign(vec2 p) {
+            return fract(52.9829189 * fract(0.06711056 * p.x + 0.00583715 * p.y));
+        }
+    
         #ifndef FXAA_DISCARD
-                //
-                // Only valid for PC OpenGL currently.
-                // Probably will not work when FXAA_GREEN_AS_LUMA = 1.
-                //
-                // 1 = Use discard on pixels which don't need AA.
-                //     For APIs which enable concurrent TEX+ROP from same surface.
-                // 0 = Return unchanged color on pixels which don't need AA.
-                //
                 #define FXAA_DISCARD 0
         #endif
     
@@ -44,7 +58,6 @@ export const baseTextureToRenderShader = new ShaderMaterial({
     
         #define NUM_SAMPLES 5
     
-        // assumes colors have premultipliedAlpha, so that the calculated color contrast is scaled by alpha
         float contrast( vec4 a, vec4 b ) {
                 vec4 diff = abs( a - b );
                 return max( max( max( diff.r, diff.g ), diff.b ), diff.a );
@@ -69,9 +82,6 @@ export const baseTextureToRenderShader = new ShaderMaterial({
                 vec4 rgbaE = FxaaTexOff(tex, posM, vec2( 1.0, 0.0), fxaaQualityRcpFrame.xy);
                 vec4 rgbaN = FxaaTexOff(tex, posM, vec2( 0.0,-1.0), fxaaQualityRcpFrame.xy);
                 vec4 rgbaW = FxaaTexOff(tex, posM, vec2(-1.0, 0.0), fxaaQualityRcpFrame.xy);
-                // . S .
-                // W M E
-                // . N .
     
                 bool earlyExit = max( max( max(
                         contrast( rgbaM, rgbaN ),
@@ -79,9 +89,6 @@ export const baseTextureToRenderShader = new ShaderMaterial({
                         contrast( rgbaM, rgbaE ) ),
                         contrast( rgbaM, rgbaW ) )
                         < fxaaQualityEdgeThreshold;
-                // . 0 .
-                // 0 0 0
-                // . 0 .
     
                 #if (FXAA_DISCARD == 1)
                         if(earlyExit) FxaaDiscard;
@@ -98,44 +105,22 @@ export const baseTextureToRenderShader = new ShaderMaterial({
                 relativeVContrast *= fxaaQualityinvEdgeThreshold;
     
                 bool horzSpan = relativeVContrast > 0.;
-                // . 1 .
-                // 0 0 0
-                // . 1 .
     
-                // 45 deg edge detection and corners of objects, aka V/H contrast is too similar
                 if( abs( relativeVContrast ) < .3 ) {
-                        // locate the edge
                         vec2 dirToEdge;
                         dirToEdge.x = contrastE > contrastW ? 1. : -1.;
                         dirToEdge.y = contrastS > contrastN ? 1. : -1.;
-                        // . 2 .      . 1 .
-                        // 1 0 2  ~=  0 0 1
-                        // . 1 .      . 0 .
-    
-                        // tap 2 pixels and see which ones are "outside" the edge, to
-                        // determine if the edge is vertical or horizontal
     
                         vec4 rgbaAlongH = FxaaTexOff(tex, posM, vec2( dirToEdge.x, -dirToEdge.y ), fxaaQualityRcpFrame.xy);
                         float matchAlongH = contrast( rgbaM, rgbaAlongH );
-                        // . 1 .
-                        // 0 0 1
-                        // . 0 H
     
                         vec4 rgbaAlongV = FxaaTexOff(tex, posM, vec2( -dirToEdge.x, dirToEdge.y ), fxaaQualityRcpFrame.xy);
                         float matchAlongV = contrast( rgbaM, rgbaAlongV );
-                        // V 1 .
-                        // 0 0 1
-                        // . 0 .
     
                         relativeVContrast = matchAlongV - matchAlongH;
                         relativeVContrast *= fxaaQualityinvEdgeThreshold;
     
-                        if( abs( relativeVContrast ) < .3 ) { // 45 deg edge
-                                // 1 1 .
-                                // 0 0 1
-                                // . 0 1
-    
-                                // do a simple blur
+                        if( abs( relativeVContrast ) < .3 ) {
                                 return mix(
                                         rgbaM,
                                         (rgbaN + rgbaS + rgbaE + rgbaW) * .25,
@@ -148,9 +133,6 @@ export const baseTextureToRenderShader = new ShaderMaterial({
     
                 if(!horzSpan) rgbaN = rgbaW;
                 if(!horzSpan) rgbaS = rgbaE;
-                // . 0 .      1
-                // 1 0 1  ->  0
-                // . 0 .      1
     
                 bool pairN = contrast( rgbaM, rgbaN ) > contrast( rgbaM, rgbaS );
                 if(!pairN) rgbaN = rgbaS;
@@ -196,15 +178,13 @@ export const baseTextureToRenderShader = new ShaderMaterial({
                 }
     
     
-                if ( !doneP && !doneN ) return rgbaM; // failed to find end of edge
+                if ( !doneP && !doneN ) return rgbaM;
     
                 float dist = min(
                         doneN ? float( iterationsUsedN ) / float( NUM_SAMPLES - 1 ) : 1.,
                         doneP ? float( iterationsUsedP ) / float( NUM_SAMPLES - 1 ) : 1.
                 );
     
-                // hacky way of reduces blurriness of mostly diagonal edges
-                // but reduces AA quality
                 dist = pow(dist, .5);
     
                 dist = 1. - dist;
@@ -220,18 +200,33 @@ export const baseTextureToRenderShader = new ShaderMaterial({
                 const float edgeDetectionQuality = .2;
                 const float invEdgeDetectionQuality = 1. / edgeDetectionQuality;
     
-                gl_FragColor = sRGBTransferOETF(FxaaPixelShader(
+                vec4 srgbColor = sRGBTransferOETF(FxaaPixelShader(
                         vUv,
                         tDiffuse,
                         resolution,
-                        edgeDetectionQuality, // [0,1] contrast needed, otherwise early discard
+                        edgeDetectionQuality,
                         invEdgeDetectionQuality
                 ));
+    
+                // ---- 终处理抖动（dither）：消除 8bit 输出量化的色带 ----
+                // 屏幕 framebuffer 只有 8bit，柔和渐变（外辉光/天空/雾/bloom 衰减）在此被量化成
+                // 肉眼可见的"一层一层"台阶。叠加 ±0.5 LSB（总跨度 1/255）的屏幕空间随机噪声后，
+                // 台阶被打散成高频颗粒——人眼对高频噪声极不敏感，色带随即消失（2026-09-06 修）。
+                // 注意：dither 只补偿「最终 8bit 输出」这一步；中间 RT 的线性量化色带由
+                // ThreeBase 的 baseRenderTarget/screenRenderTarget 改 HalfFloatType 根治。
+                // 二者缺一不可：半浮点恢复渐变连续性，dither 消除「源数据动态范围不足」型色带
+                // （如 SpriteText3 外辉光 R 通道在源图只有 39~46 共 8 个码值，34px 上必然每 5px 一跳）。
+                float dither = (ign(gl_FragCoord.xy) - 0.5) * (1.0 / 255.0) * uDitherStrength;
+                gl_FragColor = vec4(srgbColor.rgb + dither, srgbColor.a);
             ${ShaderChunk.logdepthbuf_fragment}
         }
-    `,
-    blending: NoBlending, // 渲染时不与背景融合计算 直接替换
-    depthTest: false,
-    depthWrite: false,
-    transparent: true
-});
+    `,
+    blending: NoBlending,
+    depthTest: false,
+    depthWrite: false,
+    transparent: true,
+    // 终处理：手写 sRGBTransferOETF 已是唯一一次 sRGB 编码；关闭 three 的自动 tonemap/colorspace 注入，
+    // 防止渲染到屏幕时被 three 再编码一次（本 ShaderMaterial 不写 include 块，three 本就不会注入，
+    // 这里显式置 false 仅是防御，保证颜色空间语义单一可控）。
+    toneMapped: false,
+});