@metagl/sdk-render 1.0.2 → 1.0.4

package/lacdt.render.d.ts

@@ -1,4 +1,4 @@
-import { Cartesian3, Color, Viewer, Cartesian4, Rectangle, Cesium3DTileset, ClippingPolygonCollection } from 'cesium';
+import { Cartesian3, Color, Viewer, PostProcessStage, Cartesian4, Rectangle, Cesium3DTileset, ClippingPolygonCollection } from 'cesium';
 import { Render as Render$1 } from '@/system/RenderCore';
 
 /**
@@ -51,7 +51,7 @@ declare class LightingSystem implements RenderSystem {
     /**
      * 默认配置 - 从 EnvironmentDefaults 统一管理
      */
-    private static readonly DEFAULT_CONFIG;
+    private static DEFAULT_CONFIG;
     /**
      * 构造函数
      * @param viewer - Viewer
@@ -126,7 +126,7 @@ declare class ShadowSystem implements RenderSystem {
     /**
      * 默认配置 - 从 EnvironmentDefaults 统一管理
      */
-    private static readonly DEFAULT_CONFIG;
+    private static DEFAULT_CONFIG;
     /**
      * 构造函数
      * @param viewer -  Cesium Viewer 实例
@@ -207,40 +207,57 @@ declare class VolumetricCloudsSystem implements RenderSystem {
     private isEnabled;
     private stage?;
     private preRenderListener?;
+    private noiseTexture?;
+    private fadeRafId?;
+    /** 云 Stage 添加到 postProcessStages 后触发，供外部（RenderCore）做顺序修正 */
+    onInitialized?: () => void;
     /**
      * 默认可见性控制配置
      */
-    private static readonly DEFAULT_VISIBILITY_CONFIG;
+    private static DEFAULT_VISIBILITY_CONFIG;
     /**
      * 默认配置 - 从 EnvironmentDefaults 统一管理
      */
-    private static readonly DEFAULT_CONFIG;
+    private static DEFAULT_CONFIG;
     /**
      * 构造函数
      */
     constructor(viewer: Viewer, config?: VolumetricCloudsConfig);
     /**
-     * 更新云层可见性
+     * 更新云层高度可见性（通过 cloudCover 系数控制，不禁用 Stage）
+     * 淡入动画进行中时跳过，避免覆盖动画值
      */
     private updateCloudVisibility;
     /**
-     * 初始化
+     * 初始化（异步：先加载 Blue Noise 纹理）
+     * Stage 只创建一次，后续 enable/disable 通过 cloudCover=0 控制可见性
      */
     initialize(): void;
+    private _doInitialize;
     /**
      * 获取真实地球半径
      */
     private getRealPlanetRadius;
+    /**
+     * 返回当前 PostProcessStage 实例（供 RenderCore 做顺序修正）
+     */
+    getStage(): PostProcessStage | undefined;
     /**
      * 更新uniforms
      */
     private updateUniforms;
     /**
      * 启用体积云系统
+     * 不重建 Stage，从 cloudCover=0 线性淡入到配置值
      */
     enable(): void;
+    /**
+     * 从当前 cloudCover 线性淡入/淡出到目标值，持续约 1.5 秒
+     */
+    private _startFade;
     /**
      * 禁用体积云系统
+     * 不移除 Stage，从当前云量线性淡出到 0，动画结束后标记禁用
      */
     disable(): void;
     /**
@@ -261,6 +278,7 @@ declare class VolumetricCloudsSystem implements RenderSystem {
     saveConfig(): any;
     /**
      * 获取着色器代码
+     * 严格按照 docs/环境系统/volumetric-cloud.md 实现
      */
     private getShader;
     /**
@@ -269,166 +287,6 @@ declare class VolumetricCloudsSystem implements RenderSystem {
     destroy(): void;
 }
 
-/**
- * 相机监听配置接口
- */
-interface CameraListenerConfig {
-    /** 是否启用相机监听 */
-    enabled?: boolean;
-    /** 最小高度（米） */
-    minHeight?: number;
-    /** 最大高度（米） */
-    maxHeight?: number;
-    /** 过渡范围（米） */
-    transitionRange?: number;
-    /** 强度计算回调函数 */
-    intensityCallback?: (cameraHeight: number, config: CameraListenerConfig) => number;
-}
-/**
- * 相机监听器类 - 全局管理相机高度与效果强度的关系
- */
-declare class CameraListener {
-    private viewer;
-    private config;
-    private listeners;
-    private preRenderListener?;
-    private isEnabled;
-    /**
-     * 默认配置
-     */
-    private static readonly DEFAULT_CONFIG;
-    /**
-     * 构造函数
-     */
-    constructor(viewer: Viewer, config?: CameraListenerConfig);
-    /**
-     * 初始化相机监听
-     */
-    initialize(): void;
-    /**
-     * 添加强度变化监听器
-     */
-    addListener(callback: (intensity: number) => void): void;
-    /**
-     * 移除强度变化监听器
-     */
-    removeListener(callback: (intensity: number) => void): void;
-    /**
-     * 通知所有监听器强度变化
-     */
-    private notifyListeners;
-    /**
-     * 更新配置
-     */
-    update(config: Partial<CameraListenerConfig>): void;
-    /**
-     * 启用相机监听
-     */
-    enable(): void;
-    /**
-     * 禁用相机监听
-     */
-    disable(): void;
-    /**
-     * 获取当前状态
-     */
-    getStatus(): boolean;
-    /**
-     * 获取当前配置
-     */
-    getConfig(): CameraListenerConfig;
-    /**
-     * 计算当前强度（同步调用）
-     */
-    getCurrentIntensity(): number;
-    /**
-     * 销毁相机监听器
-     */
-    destroy(): void;
-}
-/**
- * 相机监听系统配置
- */
-interface CameraListenerSystemConfig {
-    /** 体积云系统相机监听配置 */
-    volumetricClouds?: CameraListenerConfig;
-    /** 距离雾系统相机监听配置 */
-    distanceFog?: CameraListenerConfig;
-    /** 高度雾系统相机监听配置 */
-    heightFog?: CameraListenerConfig;
-    /** 大气散射系统相机监听配置 */
-    atmosphereScattering?: CameraListenerConfig;
-}
-/**
- * 相机监听系统 - 全局管理多个系统的相机高度监听
- */
-declare class CameraListenerSystem {
-    private viewer;
-    private config;
-    private listeners;
-    private isInitialized;
-    /**
-     * 默认配置
-     */
-    private static readonly DEFAULT_CONFIG;
-    /**
-     * 构造函数
-     */
-    constructor(viewer: Viewer, config?: CameraListenerSystemConfig);
-    /**
-     * 初始化相机监听系统
-     */
-    initialize(): void;
-    /**
-     * 获取特定系统的相机监听器
-     */
-    getListener(systemName: string): CameraListener | undefined;
-    /**
-     * 添加系统监听器
-     */
-    addListener(systemName: string, callback: (intensity: number) => void): void;
-    /**
-     * 移除系统监听器
-     */
-    removeListener(systemName: string, callback: (intensity: number) => void): void;
-    /**
-     * 更新系统配置
-     */
-    updateSystemConfig(systemName: string, config: Partial<CameraListenerConfig>): void;
-    /**
-     * 更新整体配置
-     */
-    update(config: Partial<CameraListenerSystemConfig>): void;
-    /**
-     * 启用所有相机监听
-     */
-    enableAll(): void;
-    /**
-     * 禁用所有相机监听
-     */
-    disableAll(): void;
-    /**
-     * 启用特定系统的相机监听
-     */
-    enableSystem(systemName: string): void;
-    /**
-     * 禁用特定系统的相机监听
-     */
-    disableSystem(systemName: string): void;
-    /**
-     * 销毁相机监听系统
-     */
-    destroy(): void;
-    /**
-     * 获取当前状态
-     */
-    getStatus(): Record<string, boolean>;
-    /**
-     * 获取所有系统配置
-     */
-    getConfig(): CameraListenerSystemConfig;
-}
-
 /**
  * 大气散射系统配置
  */
@@ -440,7 +298,6 @@ interface AtmosphereScatteringConfig {
     absorptionIntensity?: number;
     bDensity?: number;
     bColor?: Color;
-    visibility?: CameraListenerConfig;
     baseBetaR_R?: number;
     baseBetaR_G?: number;
     baseBetaR_B?: number;
@@ -454,9 +311,7 @@ interface AtmosphereScatteringConfig {
     hM?: number;
     hA?: number;
     absorption_falloff?: number;
-    groundHeight?: number;
     atmosphereThickness?: number;
-    enableGroundMix?: boolean;
 }
 /**
  * 大气散射系统
@@ -466,21 +321,18 @@ declare class AtmosphereScatteringSystem implements RenderSystem {
     private config;
     private isEnabled;
     private stage?;
-    private preRenderListener?;
-    private cameraListener?;
     private defaultSkyAtmosphereShow;
-    /**
-     * 默认可见性控制配置
-     */
-    private static readonly DEFAULT_VISIBILITY_CONFIG;
+    /** 大气 Stage 添加到 postProcessStages 后触发，供外部（RenderCore）做顺序修正 */
+    onInitialized?: () => void;
     /**
      * 默认配置对象 - 从 EnvironmentDefaults 统一管理
      */
-    private static readonly DEFAULT_CONFIG;
+    private static DEFAULT_CONFIG;
     /**
-     * 更新大气散射可见性
+     * 获取真实地球半径（与体积云系统保持一致）
+     * 动态计算基于相机位置的椭球体半径，考虑纬度影响
      */
-    private updateAtmosphereVisibility;
+    private getRealPlanetRadius;
     /**
      * 构造函数
      */
@@ -489,6 +341,10 @@ declare class AtmosphereScatteringSystem implements RenderSystem {
      * 初始化大气散射后处理效果
      */
     initialize(): void;
+    /**
+     * 返回当前 PostProcessStage 实例（供 RenderCore 做顺序修正）
+     */
+    getStage(): PostProcessStage | undefined;
     /**
      * 启用大气散射系统
      */
@@ -557,7 +413,7 @@ declare class DistanceFogSystem implements RenderSystem {
     /**
      * 默认配置 - 从 EnvironmentDefaults 统一管理
      */
-    private static readonly DEFAULT_CONFIG;
+    private static DEFAULT_CONFIG;
     /**
      * 更新雾效可见性
      */
@@ -643,7 +499,7 @@ declare class HeightFogSystem implements RenderSystem {
     /**
      * 默认配置 - 从 EnvironmentDefaults 统一管理
      */
-    private static readonly DEFAULT_CONFIG;
+    private static DEFAULT_CONFIG;
     /**
      * 更新雾效可见性
      */
@@ -697,98 +553,372 @@ declare class HeightFogSystem implements RenderSystem {
 }
 
 /**
- * 后处理系统配置
+ * 后处理系统完整配置
+ *
+ * 色彩空间说明：
+ *   Cesium 自定义 PostProcessStage 的 colorTexture，在 HDR 开启时经过
+ *   Tone Mapping 后已是 sRGB 编码的 [0,1] 值。
+ *   所有自定义 Shader 均在 sRGB 空间操作，禁止做 gamma pow() 校正。
+ *
+ * Cesium 内部 Pipeline（执行顺序）：
+ *   场景渲染 → MSAA 解析 → AmbientOcclusion → Bloom →
+ *   Tone Mapping (HDR→sRGB, 使用 exposure+tonemapper) →
+ *   [自定义 Stage: 白平衡] → [自定义 Stage: 色彩调整] →
+ *   [自定义 Stage: 阴影着色] → [自定义 Stage: 视觉增强(vignette+sharpen+chroma)] →
+ *   [DOF（如启用）] → FXAA → 显示
  */
 interface PostProcessingConfig {
     enabled?: boolean;
-    brightness?: number;
+    /** 高动态范围渲染 */
+    hdrEnabled?: boolean;
+    /** FXAA 快速近似抗锯齿 */
+    fxaaEnabled?: boolean;
+    /** MSAA 多重采样抗锯齿开关 */
+    msaaEnabled?: boolean;
+    /** MSAA 采样倍数 1/2/4/8 */
+    msaa?: number;
+    /**
+     * Cesium 原生色调映射算法
+     * 'ACES' | 'REINHARD' | 'PBR_NEUTRAL'
+     * 默认 PBR_NEUTRAL（2024-09 后 Cesium 新默认值，色彩最自然）
+     */
+    tonemapper?: string;
+    /**
+     * 曝光（Cesium 原生 postProcessStages.exposure）
+     * ⚠️  这是线性亮度乘数，不是 EV 单位！
+     *   1.0 = 中性（无变化）
+     *   <1.0 = 变暗（0.0 = 完全变黑！）
+     *   >1.0 = 变亮
+     * 实用范围：0.5 ~ 2.0，默认 1.0
+     */
+    exposure?: number;
+    /** 对比度（1.0 = 无变化，>1 增强，<1 减弱，范围 0.5~2.0）*/
     contrast?: number;
+    /** 饱和度（1.0 = 原始，0 = 灰度，>1 增强，范围 0~3.0）*/
     saturation?: number;
-    gamma?: number;
+    /** 色温 Kelvin（6500K = 日光中性，<6500K 暖色，>6500K 冷色，范围 3000~12000）*/
     temperature?: number;
+    /** 色调（0 = 中性，-1 偏洋红，+1 偏绿，范围 -1~1）*/
     tint?: number;
+    /** 阴影叠色 RGB（Cartesian3，分量范围 0~1）*/
     shadowColor?: Cartesian3;
+    /** 阴影叠色强度（推荐 0.01~0.05）*/
     shadowBlend?: number;
-    hdrEnabled?: boolean;
-    fxaaEnabled?: boolean;
-    msaaEnabled?: boolean;
-    msaa?: number;
+    /** 是否启用 Bloom 泛光 */
+    bloomEnabled?: boolean;
+    /** Bloom 对比度（-255~255，默认 128）*/
+    bloomContrast?: number;
+    /** Bloom 亮度阈值偏移（HSB空间，默认 -0.3，负值=只让高亮区泛光）*/
+    bloomBrightness?: number;
+    /** Bloom 高斯模糊 sigma（越大光晕越宽，默认 2.0）*/
+    bloomSigma?: number;
+    /** Bloom 采样步长（默认 1.0，增大加速但降质）*/
+    bloomStepSize?: number;
+    /**
+     * Bloom 仅显示泛光层（不叠加原始场景）
+     * false（默认）= 正常叠加；true = 仅显示光晕（调试用）
+     * ⚠️ 与大气散射同时开启时：建议保持 false；
+     *    Bloom 在 ToneMapping 之前处理 HDR 亮点，与大气在 ToneMapping 之后叠加不冲突。
+     */
+    bloomGlowOnly?: boolean;
+    /** 是否启用 AO */
+    aoEnabled?: boolean;
+    /** AO 遮蔽强度（pow 指数，越大阴影越深，推荐 1.5~4.0，默认 3.0）
+     *  ⚠️ 过高（>6）会产生全黑或条纹，与 Bloom 同时启用时建议 ≤ 3.0 */
+    aoIntensity?: number;
+    /** AO 自遮蔽偏差角（弧度，防止平面自遮蔽，默认 0.1）*/
+    aoBias?: number;
+    /**
+     * AO 采样半径系数（Cesium 1.124+ 新算法）
+     * 与相机距离和深度联动，自动缩放。
+     * 推荐范围 0.01~0.05，默认 0.02（兼容旧算法的安全值）
+     * ⚠️ 过大（>0.1）会产生斜条纹伪影
+     */
+    aoLengthCap?: number;
+    /**
+     * AO 每方向采样步数（Cesium 1.124+ 新算法，默认 32）
+     * 值越大质量越高但性能越低；推荐 8~16 以避免条纹
+     * ⚠️ 过高（>32）在某些 GPU 上会产生闪烁，建议使用 8
+     */
+    aoStepCount?: number;
+    /**
+     * AO 采样方向数（Cesium 1.124+ 新算法，默认 6）
+     * 推荐 6~8，方向数越多越均匀、条纹越少
+     */
+    aoDirectionCount?: number;
+    /** 是否启用景深 */
+    dofEnabled?: boolean;
+    /** 焦距（米，相机到焦平面的距离）*/
+    dofFocalDistance?: number;
+    /** 景深模糊 sigma（越大焦外虚化越强，默认 3.78）*/
+    dofSigma?: number;
+    /** 暗角（vignette）强度（0 = 无暗角，1.5 = 明显暗角，范围 0~2）*/
+    vignetteStrength?: number;
+    /** 暗角柔和度（0.2 = 硬边，0.8 = 柔和过渡，范围 0.1~1.0）*/
+    vignetteSoftness?: number;
+    /** 锐化强度（0 = 不锐化，1 = 标准，2 = 强锐化，范围 0~2）*/
+    sharpness?: number;
+    /** 色差强度（0 = 无色差，0.005 = 轻微，范围 0~0.02）*/
+    chromaticAberration?: number;
 }
-/**
- * 后处理系统
- */
 declare class PostProcessingSystem implements RenderSystem {
     private viewer;
     private config;
     private isEnabled;
+    /** 自定义 Shader Stage */
     private stages;
+    /** Cesium 原生 DOF stage（通过 PostProcessStageLibrary 创建）*/
+    private dofStage;
+    private static DEFAULT_CONFIG;
+    constructor(viewer: Viewer, config?: PostProcessingConfig);
+    private createStages;
+    initialize(): void;
+    enable(): void;
+    disable(): void;
+    update(config: Partial<PostProcessingConfig>): void;
+    getStatus(): boolean;
+    getConfig(): PostProcessingConfig;
+    saveConfig(): any;
+    destroy(): void;
+    /** 应用 Cesium 色调映射算法 */
+    private applyTonemapper;
+    /** 应用 Bloom 配置
+     *
+     * ⚠️ 与大气散射系统同时启用时的注意事项：
+     *   Bloom 在 Tone Mapping 之前（线性 HDR 空间）执行，针对高亮区域泛光。
+     *   大气散射 Stage 在 Tone Mapping 之后叠加（sRGB 域），两者执行阶段不同，无直接冲突。
+     *   但视觉上太阳周围会有 Bloom 光晕 + 大气散射日晕的双重叠加，
+     *   建议：bloomBrightness 调高（如 -0.1 ~ 0），bloomSigma 收小（1.0~1.5）。
+     *
+     * brightness uniform 行为：对 Bloom 提取出的高亮区转到 HSB 空间后，
+     * 直接加到 B 通道。负值（默认 -0.3）= 减少高亮提取范围（更少区域泛光）。
+     * 这不是一个亮度阈值！它会整体偏移泛光层的亮度，调得太低会使泛光层变暗
+     * 进而影响整个画面色调。建议范围：-0.5 ~ 0.2
+     */
+    private applyBloom;
+    /** 应用 AO 配置（Cesium 1.124+ 新算法 HBAO v2）
+     *
+     * 新算法使用 Gaussian 分布替代固定步长，stepCount/directionCount 为必要参数。
+     *
+     * ⚠️ AO + Bloom 同时开启时：两者共用帧缓冲，Cesium 1.124+ 已修复冲突，
+     *    但需确保 intensity ≤ 4.0，lengthCap ≤ 0.05，stepCount ≤ 16，
+     *    否则 AO 计算量溢出会导致 GPU 驱动降频，表现为画面变黑/闪烁。
+     *
+     * 斜条纹伪影根因：
+     *   - randomTexture 只有 255×255，低分辨率随机旋转方向导致沿对角线的方向重复
+     *   - lengthCap 过大 + stepCount 过高时，步长穿过深度不连续区域，产生错误遮蔽
+     *   修复：stepCount=8, directionCount=6, lengthCap=0.02（官方推荐安全值）
+     */
+    private applyAO;
+    /** 应用/创建 DOF 景深 */
+    private applyDOF;
     /**
-     * 默认配置 - 从 EnvironmentDefaults 统一管理
+     * 白平衡 Shader
+     * 输入：tone-mapped sRGB [0,1]
+     *
+     * temperature：Planckian locus 拟合的 RGB 通道缩放，以 6500K 为归一基准。
+     * tint：绿-洋红轴 ±0.12 感知均匀偏移。
+     *
+     * 与大气散射系统兼容处理：
+     *   大气散射计算出的天空颜色（高饱和蓝色）叠加到 sRGB 帧上后，
+     *   全局白平衡会对天空蓝色做额外偏移（暖色温压蓝 → 天空偏绿）。
+     *   通过亮度保护系数（protectHighlights）对高亮区域（天空/太阳）
+     *   渐进减弱白平衡强度，保留大气颜色的物理真实性。
+     */
+    private getWhiteBalanceShader;
+    /**
+     * 色彩调整 Shader
+     * 输入：白平衡后的 sRGB [0,1]
+     *
+     * 在 sRGB 空间做 contrast + saturation，与 Lightroom/达芬奇行为一致。
+     * 不做 gamma pow()，避免双重 gamma 过曝。
+     */
+    private getColorAdjustmentShader;
+    /**
+     * 阴影着色 Shader
+     * 对暗部叠加 shadowColor，smoothstep 防止硬边条纹。
+     */
+    private getShadowColorShader;
+    /**
+     * 视觉增强 Shader（合并单 Pass，降低性能开销）
+     * 输入：阴影着色后的 sRGB [0,1]
+     *
+     * 包含三个效果：
+     *
+     * 1. 锐化（Unsharp Mask）
+     *    对 3x3 邻域取平均，用 original + strength*(original - blur) 增强细节。
+     *    sharpness=0 完全跳过，sharpness=1 标准增强。
+     *
+     * 2. 色差（Chromatic Aberration）
+     *    R/G/B 三通道向屏幕中心方向做微小偏移采样，模拟镜头色差。
+     *    chromaticAberration=0 完全跳过，建议范围 0~0.008。
+     *
+     * 3. 暗角（Vignette）
+     *    使用距屏幕中心的归一化距离 smoothstep 生成渐变暗角。
+     *    vignetteStrength 控制强度，vignetteSoftness 控制过渡范围。
+     *    最后执行，确保暗角叠加在所有效果之上。
+     */
+    private getVisualEnhanceShader;
+}
+
+/**
+ * 相机监听配置接口
+ */
+interface CameraListenerConfig {
+    /** 是否启用相机监听 */
+    enabled?: boolean;
+    /** 最小高度（米） */
+    minHeight?: number;
+    /** 最大高度（米） */
+    maxHeight?: number;
+    /** 过渡范围（米） */
+    transitionRange?: number;
+    /** 强度计算回调函数 */
+    intensityCallback?: (cameraHeight: number, config: CameraListenerConfig) => number;
+}
+/**
+ * 相机监听器类 - 全局管理相机高度与效果强度的关系
+ */
+declare class CameraListener {
+    private viewer;
+    private config;
+    private listeners;
+    private preRenderListener?;
+    private isEnabled;
+    /**
+     * 默认配置
      */
     private static readonly DEFAULT_CONFIG;
     /**
      * 构造函数
-     * @param viewer
-     * @param config
      */
-    constructor(viewer: Viewer, config?: PostProcessingConfig);
+    constructor(viewer: Viewer, config?: CameraListenerConfig);
     /**
-     * 创建后处理阶段
-     * @returns
+     * 初始化相机监听
      */
-    private createStages;
+    initialize(): void;
     /**
-     * 初始化后处理系统
+     * 添加强度变化监听器
      */
-    initialize(): void;
+    addListener(callback: (intensity: number) => void): void;
     /**
-     * 启用后处理
-     * @returns
+     * 移除强度变化监听器
+     */
+    removeListener(callback: (intensity: number) => void): void;
+    /**
+     * 通知所有监听器强度变化
+     */
+    private notifyListeners;
+    /**
+     * 更新配置
+     */
+    update(config: Partial<CameraListenerConfig>): void;
+    /**
+     * 启用相机监听
      */
     enable(): void;
     /**
-     * 禁用后处理
-     * @returns
+     * 禁用相机监听
      */
     disable(): void;
     /**
-     * 更新后处理配置
-     * @param config
+     * 获取当前状态
      */
-    update(config: Partial<PostProcessingConfig>): void;
+    getStatus(): boolean;
     /**
-     * 获取后处理状态
-     * @returns
+     * 获取当前配置
      */
-    getStatus(): boolean;
+    getConfig(): CameraListenerConfig;
     /**
-     * 获取后处理配置
-     * @returns
+     * 计算当前强度（同步调用）
      */
-    getConfig(): PostProcessingConfig;
+    getCurrentIntensity(): number;
     /**
-     * 保存配置为 JSON 对象
+     * 销毁相机监听器
      */
-    saveConfig(): any;
+    destroy(): void;
+}
+/**
+ * 相机监听系统配置
+ */
+interface CameraListenerSystemConfig {
+    /** 体积云系统相机监听配置 */
+    volumetricClouds?: CameraListenerConfig;
+    /** 距离雾系统相机监听配置 */
+    distanceFog?: CameraListenerConfig;
+    /** 高度雾系统相机监听配置 */
+    heightFog?: CameraListenerConfig;
+    /** 大气散射系统相机监听配置 */
+    atmosphereScattering?: CameraListenerConfig;
+}
+/**
+ * 相机监听系统 - 全局管理多个系统的相机高度监听
+ */
+declare class CameraListenerSystem {
+    private viewer;
+    private config;
+    private listeners;
+    private isInitialized;
     /**
-     * 获取颜色调整着色器
-     * @returns
+     * 默认配置
      */
-    private getColorAdjustmentShader;
+    private static readonly DEFAULT_CONFIG;
     /**
-     * 获取阴影颜色着色器
-     * @returns
+     * 构造函数
      */
-    private getShadowColorShader;
+    constructor(viewer: Viewer, config?: CameraListenerSystemConfig);
     /**
-     * 获取白平衡着色器
-     * @returns
+     * 初始化相机监听系统
      */
-    private getWhiteBalanceShader;
+    initialize(): void;
     /**
-     * 销毁系统
+     * 获取特定系统的相机监听器
+     */
+    getListener(systemName: string): CameraListener | undefined;
+    /**
+     * 添加系统监听器
+     */
+    addListener(systemName: string, callback: (intensity: number) => void): void;
+    /**
+     * 移除系统监听器
+     */
+    removeListener(systemName: string, callback: (intensity: number) => void): void;
+    /**
+     * 更新系统配置
+     */
+    updateSystemConfig(systemName: string, config: Partial<CameraListenerConfig>): void;
+    /**
+     * 更新整体配置
+     */
+    update(config: Partial<CameraListenerSystemConfig>): void;
+    /**
+     * 启用所有相机监听
+     */
+    enableAll(): void;
+    /**
+     * 禁用所有相机监听
+     */
+    disableAll(): void;
+    /**
+     * 启用特定系统的相机监听
+     */
+    enableSystem(systemName: string): void;
+    /**
+     * 禁用特定系统的相机监听
+     */
+    disableSystem(systemName: string): void;
+    /**
+     * 销毁相机监听系统
      */
     destroy(): void;
+    /**
+     * 获取当前状态
+     */
+    getStatus(): Record<string, boolean>;
+    /**
+     * 获取所有系统配置
+     */
+    getConfig(): CameraListenerSystemConfig;
 }
 
 /**
@@ -1978,6 +2108,16 @@ declare class Render {
     private systems;
     constructor(config: RenderConfig);
     private init;
+    /**
+     * 确保 PostProcessStage 的渲染顺序正确：云 Stage 先，大气 Stage 后
+     *
+     * 原因：云系统是异步初始化（需加载纹理），大气系统是同步的，
+     * "先开大气再开云"时大气 Stage 会排在云 Stage 前面，渲染效果错误。
+     *
+     * 修正方式：直接操作 PostProcessStageCollection 的内部 _stages 数组调整顺序，
+     * 不调用 remove()（remove 会 destroy GPU 资源），不触发 Shader 重编译，无视觉闪烁。
+     */
+    private ensurePostProcessStageOrder;
     private registerSystems;
     private initialize;
     /**
@@ -2046,10 +2186,6 @@ declare class Render {
      * 读取 JSON 配置
      */
     readConfigContent(jsonContent: string | any): any;
-    /**
-     * 解析系统配置
-     */
-    private parseSystemConfig;
     /**
      * 获取各个系统实例（供高级使用）
      */
@@ -2468,47 +2604,18 @@ declare class ShadowControl extends BaseControlPanel {
 declare class PostProcessingControl extends BaseControlPanel {
     private container;
     private preset_container;
+    /** 后处理开启时需要解禁的所有控件 id */
     private disableSliders;
     constructor(viewer: Viewer, render: Render, renderConfig: RenderConfig);
-    /**
-     * 创建控制面板
-     */
     createPanel(container: HTMLElement): void;
-    /**
-     * 获取预设标签
-     */
-    private getPresetLabel;
-    /**
-     * 初始化事件监听
-     */
     initEventListeners(container: HTMLElement): void;
-    /**
-     * 应用滤镜预设
-     */
+    private getPresetLabel;
     private applyFilterPreset;
-    /**
-     * 刷新控制面板显示
-     */
     protected refreshControls(config: any): void;
-    /**
-     * 从配置更新控件状态
-     */
     private updateControlsFromConfig;
-    /**
-     * 从配置更新滑块
-     */
     private updateSliderFromConfig;
-    /**
-     * 应用默认预设
-     */
     applyDefaultPresets(): void;
-    /**
-     * 重置面板设置
-     */
     reset(): void;
-    /**
-     * 获取面板容器
-     */
     getContainer(): HTMLElement;
 }