BloomEffect 场景泛光（亮度后处理）

屏幕空间 PostProcessStage 亮度后处理：对整帧颜色缓冲做亮度过曝（mix(vec3(0), rgb, brightness)，brightness > 1 时 RGB 线性加倍，呈泛光过曝观感）。对齐源案例 Scene/Bloom——源命名「Bloom」，实际实现为 PostProcessStageLibrary.createBrightnessStage() 的亮度过曝，本类忠实复刻同一渲染方程，不引入真实 HDR bloom。

---

能力定位

BloomEffect 适合：

• 整帧提亮 / 过曝：夜间暗图整体提亮、高光强化；
• 泛光观感：brightness > 1 制造亮部过曝的「泛光」氛围（源案例取 2）；
• 与后处理扫描叠加：与 RadarSweepEffect 同为 PostProcessStage 屏幕空间后处理，可叠加共存。

与其他后处理/实体效果的区分：

效果	作用面	行为
BloomEffect（本效果）	整帧颜色缓冲（屏幕空间）	全局亮度过曝，不依赖场景几何
RadarSweepEffect	屏幕空间 + 深度重建	扫描环贴合地形表面
WeatherEffect	屏幕空间（雨雪雾）	天气粒子叠加

构造函数

constructor(options: BloomEffectOptions = {})

interface BloomEffectOptions {
  brightness?: number  // 屏幕亮度系数（RGB × brightness，>1 过曝泛光观感），默认 2（对齐源案例 Scene/Bloom）
  enabled?: boolean    // 后处理 stage 是否启用，默认 true
}

参数	类型	默认值	描述
brightness	number	2	亮度系数，1 保真、>1 过曝（对齐源案例 uniforms.brightness = 2）、<1 偏暗
enabled	boolean	true	stage 加入集合后的初始启用状态（false 时加入但暂不生效）

无必填项，new BloomEffect() 亦合法。

生命周期

实现 Lifecycle<Viewer> 契约，on/off/destroy 均幂等：

on(viewer: Viewer): void      // 创建 PostProcessStage（亮度 uniform 固定为构造时值）并加入 postProcessStages
off(viewer: Viewer): void     // 移除本效果创建的 PostProcessStage
destroy(viewer: Viewer): void // 等价于 off（并释放内部引用）

brightness 在构造时固化到 stage uniform；运行中切换亮度档位请 destroy 后以新值重建（与模板演示一致）。 源案例无销毁钩子、需手动清空；本效果实例自持单个 stage，destroy 即清理，多实例各自独立，无泄漏。

基础示例

import { BloomEffect } from '@nexa/gis-cesium'

const effect = new BloomEffect({ brightness: 2 }) // 对齐源案例：过曝泛光
effect.on(viewer)

进阶示例

多档位切换 + 与雷达扫描叠加（多实例 stage 名称各自唯一，可安全共存）：

import { BloomEffect, RadarSweepEffect } from '@nexa/gis-cesium'
import { Cartesian3 } from 'cesium'

// 亮度档位：destroy 旧实例 → 以新值重建
const levels = [0.5, 1, 2, 4]
let bloom = new BloomEffect({ brightness: 2 })
bloom.on(viewer)

const switchLevel = (level: number) => {
  bloom.destroy(viewer)
  bloom = new BloomEffect({ brightness: level })
  bloom.on(viewer)
}

// 与雷达扫描叠加（后处理链顺序执行）
const sweep = new RadarSweepEffect({ position: Cartesian3.fromDegrees(120, 30, 0) })
sweep.on(viewer)

// 演示到期后统一销毁
window.setTimeout(() => {
  bloom.destroy(viewer)
  sweep.destroy(viewer)
}, 120000)

实现说明

• 渲染方程：内联 Cesium 1.133 PostProcessStageLibrary.createBrightnessStage() 的原文着色器——out_FragColor = vec4(mix(vec3(0), rgb, brightness), 1.0)，brightness=2 即 RGB 线性加倍（高光裁切 → 泛光观感）；
• 不直接调用 createBrightnessStage()：该工厂产出的 stage 名称固定为 czm_brightness 且 name 为只读，而 PostProcessStageCollection 要求集合内名称唯一——同 viewer 下多实例会因同名冲突抛 DeveloperError。改为 new PostProcessStage({ name: \bloom_N`, fragmentShader, uniforms })`，每实例自增唯一名，多实例可安全共存；
• 资源所有权：本效果创建的 stage 由 off/destroy 移除，创建方无需单独清理；只持有自身 stage，不触碰调用方其他资源；
• 着色器版本：createBrightnessStage 源 shader 在 Cesium 1.133 已是 GLSL 3.00（texture / in / out_FragColor），直接内联复用，无迁移成本。

清理责任

effect.destroy(viewer) // 或 effect.off(viewer)，等价且幂等

重复调用 destroy/off 安全（无 stage 时为空操作）。

Cesium 版本限制

• 依赖 Cesium PostProcessStage（公开 API，RadarSweepEffect 同族）与 viewer.scene.postProcessStages；
• 后处理着色器需真实浏览器/WebGL 验证（编译、整帧亮度效果）；已验证目标版本：Cesium 1.133.1。