场景特效

约 1657 字大约 6 分钟

2024-11-26

平台支持一些场景特效，包括雾天气,雨天气,雪天气, 泛光特效,亮度效果,夜视效果,黑白效果,马赛克效果,景深效果等。

1. 特效的底层实现：后处理(Post Processing)

特效底层是使用后处理(Post Processing)来实现，后期处理的过程有点类似于照片的PS。生活中拍摄了一张自拍照，看到照片后发现它太暗了，于是我们增加亮度得到了一张新的照片。在增加亮度后发现脸上的痘痘清晰可见，这可不是我们希望的效果，于是再进行一次美肤效果处理。在这之后可能还会进行n次别的操作，直到满足我们的要求。上述这个过程和三维里面的后期处理流程非常类似：拍的原始照片相当于三维场景中实际渲染得到的效果，在此基础上进行物体描边、夜视效果、环境光遮蔽等后期处理，最后渲染到场景中的图片相当于定版的最终照片。整个过程如下图所示：

2. 特效类型清单

特效均是继承自BaseEffect类的子类对象。

目前有以下类型：

功能	类名	功能示例
对象描边	mars3d.effect.Outline	查看
对象泛光	mars3d.effect.BloomTarget	查看
雾天气	mars3d.effect.Fog	查看
雨天气	mars3d.effect.Rain	查看
雪天气	mars3d.effect.Snow	查看
地面积雪	mars3d.effect.SnowCover	查看
颜色校正	mars3d.effect.ColorCorrection	查看
泛光特效	mars3d.effect.Bloom	查看
亮度效果	mars3d.effect.Brightness	查看
马赛克效果	mars3d.effect.Mosaic	查看
景深效果	mars3d.effect.DepthOfField	查看
夜视效果	mars3d.effect.NightVision	查看
黑白效果	mars3d.effect.BlackAndWhite	查看
闪电效果	mars3d.effect.Lightning	查看
高空雾效果	mars3d.effect.HighFog	查看

3. 特效的使用

平台的所有场景特效类都继承于BaseEffect类，场景特效类均在mars3d.effect.*命名空间下面。下面我们演示创建一个场景特效对象，并调用map.addEffect添加到地图上。

控件类型清单请访问EffectType

// 雨效果
const rainEffect = new mars3d.effect.Rain({
    speed: 10,
})
map.addEffect(rainEffect)

3.1. 运行效果

新窗口查看

4. 特效的通用属性与方法

所有特效类都继承于BaseEffect，因此除各自的专有参数外，都具备下面这些通用成员：

成员	说明
`effect.id`、`effect.name`	对象标识与名称
`effect.enabled`	是否启用该特效（最常用）
`effect.destroy()`	销毁特效并释放 GPU 资源
`map.addEffect(effect)`	把特效添加到地图
`map.removeEffect(effect)`	移除特效
`map.getEffectById(id)`	按 id 获取地图上的特效
`effect.availability`	按时间范围控制特效生效（配合地图时钟）
`effect.on(type, fn)` / `off(type, fn)`	事件监听/解绑

// 统一的开关方式
const rainEffect = new mars3d.effect.Rain({ speed: 10 })
map.addEffect(rainEffect)

rainEffect.enabled = false // 关闭
rainEffect.enabled = true // 开启

// 不再使用时销毁
map.removeEffect(rainEffect)
rainEffect.destroy()

4.1 按时间范围显示特效

特效支持设置生效时间段（availability），配合地图时钟可以实现"下雨 10 秒、停 10 秒"这类时序效果：

const now = map.clock.currentTime
rainEffect.availability = [
  { start: now, stop: Cesium.JulianDate.addSeconds(now, 10, new Cesium.JulianDate()) },
  {
    start: Cesium.JulianDate.addSeconds(now, 20, new Cesium.JulianDate()),
    stop: Cesium.JulianDate.addSeconds(now, 30, new Cesium.JulianDate())
  },
  { start: Cesium.JulianDate.addSeconds(now, 40, new Cesium.JulianDate()), stop: "2999-01-01 00:00:00" }
]

4.2 特效可以叠加使用

多个特效可以同时添加、同时生效，例如"下雪 + 地面积雪 + 雾化 + 夜晚亮度"可以一起打开，这也是做"天气系统"的典型做法：

map.addEffect(new mars3d.effect.Snow({ speed: 20, maxHeight: 8000 }))
map.addEffect(new mars3d.effect.SnowCover({ alpha: 0.6, maxHeight: 8000 }))
map.addEffect(new mars3d.effect.Fog({ maxHeight: 20000 }))
map.addEffect(new mars3d.effect.Brightness({ brightness: 0.6 }))

注意：后处理型特效（泛光、亮度、颜色校正、夜视、黑白、马赛克、景深、描边）都是全屏后处理，叠加越多、GPU 压力越大，移动端建议最多同时开启 1-2 个。

5. 性能与注意事项

5.1 性能建议

特效类型	性能开销	建议
雨、雪（粒子类）	中	粒子 `size`/`speed` 不宜过大，移动端适当降低
雾、高空雾	低	可长期开启
泛光、亮度、颜色校正、夜视、黑白、马赛克、景深	中-高（全屏后处理）	同一时刻只开 1-2 个，用完及时 `enabled = false`
对象泛光、对象描边	中（逐对象渲染）	只对必要对象使用，避免大面积高亮
地面积雪 SnowCover	中	使用 `layer` 参数限定只对目标模型生效，避免全场景计算

// 页面切换/功能关闭时的正确做法
effect.enabled = false // 临时关闭，保留对象便于下次打开
// 或者彻底释放
map.removeEffect(effect)
effect.destroy()

5.2 常见问题

特效看不到效果？ 先确认 map.addEffect(effect) 已调用、enabled 为 true；泛光/夜视等特效在"全黑场景"下效果不明显，建议先有模型或亮色对象。
UI/文字也被后处理影响了？ 全屏后处理只作用于三维场景画布，不会影响 HTML 面板；但如果使用 DivGraphic 之类的 HTML 对象，它们不在后处理范围内，会显得"颜色不一致"。
局部特效点击不到对象？ 检查对象是否可拾取（popup / highlight 设置会影响）、是否需要放进 objectsToExclude；3DTiles 构件必须走 6.3 的方式。
多个特效叠加后变卡/发白？ 后处理是逐级叠加的，泛光 + 亮度 + 颜色校正同时开启很容易过曝，注意调整 brightness/contrast 等参数。

6. 特效示例清单

特效	类名	功能示例
雾天气	`mars3d.effect.Fog`	查看
高空雾	`mars3d.effect.HighFog`	查看
雨天气	`mars3d.effect.Rain`	查看
雪天气	`mars3d.effect.Snow`	查看
地面积雪	`mars3d.effect.SnowCover`	查看
闪电	`mars3d.effect.Lightning`	查看
泛光特效	`mars3d.effect.Bloom`	查看
亮度效果	`mars3d.effect.Brightness`	查看
颜色校正	`mars3d.effect.ColorCorrection`	查看
夜视效果	`mars3d.effect.NightVision`	查看
黑白效果	`mars3d.effect.BlackAndWhite`	查看
马赛克效果	`mars3d.effect.Mosaic`	查看
景深效果	`mars3d.effect.DepthOfField`	查看
对象描边	`mars3d.effect.Outline`	查看
对象泛光	`mars3d.effect.BloomTarget`	查看