06-research-three-fog-shader-reuse.md 6.4 KB

调研 —— Three.js 雾 shader 可复用面与 Cesium 深度互通可行性

Type: research Status: resolved Labels: wayfinder:research Blocked by: None

进度:100%

已关闭(resolved)。甲方 Q12 已裁定:优先采用简单、能落地的方法,极难完成的就此作罢 —— 「Cesium 深度喂给 Three」备选废止,雾气锁定单一 Cesium 渲染器的自建 PostProcessStage(路线 B),数学从 Three haze 侧搬。

产物:research/three-fog-shader-reuse.md。只读调研:未改 src/、未装依赖、未跑 build/dev。

下一步:本图 frontier 只剩 01(主场景区的配置契约);07 已只欠 01。

Question

甲方裁定(Q9=B、Q12=B):雾气走自建 Cesium depth 后处理级(路线 B),但要参考 Three.js 增强管线的 shader 源码写法,以求更好观感、更低开销;同时另立一张调研票评估「把 Cesium 深度喂给 Three」的可行性。

本票回答两件事:

  1. 可移植的数学与写法。src/plugins/useThreeGeospatial/lib/clouds(CloudsEffect.ts / CloudsMaterial.ts / README 的 haze、hazeDensityScale = 3e-5、hazeExponent = 1e-3、AerialPerspectiveEffect)里,哪些是与渲染器无关的纯数学/曲线(可搬进 Cesium 的 PostProcessStage GLSL/Cesium 方言),哪些耦合 Three 的渲染器状态(必须重写)?具体给出:雾/霾的密度函数、颜色混合公式、相位/散射项是否与太阳方向耦合、以及它对"距离"的定义(视空间深度 vs 世界距离 vs 大气路径长度)。

  2. 深度互通的真实可行性(作为备选,不改架构)。要让 Three 的雾正确遮蔽 Cesium 渲染的地形/影像/3D Tiles,需要把 Cesium 的深度缓冲喂给 Three。评估:Context.depthTexture 能否作为 Three 的 depth 输入?两者相机模型(Cesium lookAtTransform 的 HeadingPitchRange vs Three 的透视相机)与深度非线性约定如何对齐?需要多少跨渲染器同步代码、每帧成本多少、失败面有哪些?

约束(不得越界):ADR 0004 锁死「Cesium 为主、Three.js 为增强,不接管 Cesium 场景」;ADR 0007 锁死交付以 src/modules/cockpit 为准、大型插件不作为驾驶舱主体依赖。本票只做评估,结论若指向"引入第二套渲染器",必须明确标注它需要推翻/修订 ADR 0004,并交回甲方裁定 —— 不得直接建议实施。

做法:只读调研 + 网络检索 Cesium/Three 官方文档与社区实践。不要引入依赖、不要改 src/、不要跑 build/dev(AGENTS.md)。产物落 research/three-fog-shader-reuse.md,并在票面记一条指向它的链接。

Answer

甲方裁定(Q12 定案):优先采用简单、能落地的方法,极难完成的就此作罢。据此废止「把 Cesium 深度喂给 Three」这条备选:它只有两条路 —— 把 Cesium 私有 context 交给 Three(上游自 2013 年 open、明确不支持),或每帧 readPixels 回读(管线停顿、量化、动态 near/far 归一化);社区同 canvas 方案实测俯视遮挡错乱,正中驾驶舱近俯视主视角;采用它还须先推翻 ADR 0004。定案:维持单一 Cesium 渲染器,雾气走自建 PostProcessStage(路线 B),数学从 Three haze 侧搬。 07、08 只在本边界内选简单手段,不再评估第二渲染器路线。以下为裁定前的调研记录。

结论:Q1 的雾/霾数学(密度曲线、闭式光深积分、混合公式、相位函数)是与渲染器无关的纯数学,可整体搬进 Cesium 自建 PostProcessStage(路线 B 无障碍);Q2「把 Cesium 深度喂给 Three」评级=极难,且与 ADR 0004 冲突,须交回甲方裁定,本票不建议实施。 全文与证据:research/three-fog-shader-reuse.md。

  1. 密度与「距离」口径:密度=modulation·hazeDensityScale·exp(−cameraHeight·hazeExponent)(默认 3e-5 / 1e-3,clouds.frag:666),光深是沿视线的闭式解析积分(iq fog 公式,clouds.frag:671-680)。「距离」=射线-椭球求交 + 场景深度缓冲(RGBA 打包 → reverseLogDepth → 余弦修正)钳出的世界射线路径长(clouds.frag:806-814),不是视空间深度。注意 max(cosθ, 1e-5) 钳制(clouds.frag:673):一切俯视/平视视角下公式退化为 OD ≈ d₀·L 的线性距离雾——恰好适配 07 的各向同性约束。

  2. 颜色混合:C_out = C_in·(1−a) + inscatter(clouds.frag:988)。inscatter 含双 HG 相位(cosTheta = dot(sunDirection, rayDirection))+ 预计算 LUT 辐照 + 阴影长度——太阳耦合全在颜色项;距离/透射率项与太阳无关,07 用常量雾色即可完全剥离太阳,三张大气 LUT 不搬。

  3. 可搬性判定:纯数学项(密度、积分、混合、HG 相位)原样可搬;结构同构需改写(深度采样换 czm_readDepth、uniform 换成 Cesium 自动 uniform czm_inverseProjection / czm_eyeHeight / czm_ellipsoidRadii、GLSL1 方言、两套 log 深度编码互转);不可搬(EffectComposer/MRT/temporal upscale、transmittance/scattering/irradiance LUT——纯雾不需要)。详见笔记 §1.5 判定表与 §2。

  4. 默认参数不可用:默认参数(coverage 调制 0.5)下 50% 起雾 ≈ 56 km(h=200 m),比 07 的 1,651 m 预算弱 ≈ 30×;07 须把密度抬约 30 倍或换更陡曲线族。

  5. Q2 前提修正:Context.depthTexture 是布尔能力标志(是否支持 WEBGL_depth_texture,Context.js:714-725),不是纹理对象——票面与 04 笔记的表述以本票为准;真正的场景深度是 D24S8 打包纹理(DEPTH_STENCIL + UNSIGNED_INT_24_8,FramebufferManager.js:189-196),格式与 Three DepthStencilFormat 相容,但 WebGL 纹理不能跨 context 共享。

  6. Q2 评级:极难。零拷贝路线=把 Cesium 私有 context 交给 Three(上游 issue #648 自 2013 年 open,明确不支持);否则每帧 readPixels 回读(管线停顿、24bit 量化、Cesium 动态 near/far 需手动归一化);社区同 canvas 方案实测俯视/仰视遮挡错乱,正中驾驶舱近俯视主视角。该路线=引入第二套渲染器接管合成,与 ADR 0004 冲突,须交回甲方裁定。