157 lines
5.1 KiB
Markdown
157 lines
5.1 KiB
Markdown
# MapLibreParticleLab 粒子连续渲染静态底图缓存与动画快路径优化规划 v1
|
||
|
||
## 1. 目标
|
||
STEP-086 已确认：Particle / WeatherColor 的 needsRepaint 会通过全局 repaint 让完整 MapLibre scene 连续出帧。React 不会每帧重新提交 PBF，但 Native Renderer 会重复进入 source/layer orchestration，并重新提交静态 PBF/fill/line/symbol draw。
|
||
|
||
本规划目标：
|
||
- 地图真实变化时仍走 Full Frame。
|
||
- Camera、Style、Tile 稳定且只有 WeatherColor/Particle 动画时，复用 Static Underlay。
|
||
- NavSea / React 不参与 Renderer cache 管理。
|
||
- 不改变 NavSea ↔ Particle C-001 公共边界。
|
||
|
||
## 2. 当前关键代码
|
||
必须以当前 origin/particle/main 实际代码为准，重点包括：
|
||
- src/mbgl/renderer/layers/render_particle_validation_layer.cpp
|
||
- src/mbgl/renderer/layers/render_weather_color_layer.cpp
|
||
- src/mbgl/renderer/render_orchestrator.cpp/.hpp
|
||
- src/mbgl/renderer/renderer.cpp
|
||
- src/mbgl/renderer/renderer_impl.cpp/.hpp
|
||
- src/mbgl/map/map_impl.cpp
|
||
- include/mbgl/renderer/render_target.hpp
|
||
- src/mbgl/renderer/render_target.cpp
|
||
- src/mbgl/renderer/layers/render_heatmap_layer.cpp
|
||
- src/mbgl/renderer/layers/render_hillshade_layer.cpp
|
||
|
||
## 3. 核心结构
|
||
不增加永久 public static/dynamic layer flag。采用 Renderer 内部 retained dynamic boundary：
|
||
- WeatherColor 是 boundary candidate。
|
||
- RasterParticle 是 boundary candidate。
|
||
- 同时存在时取最小 layerIndex。
|
||
- boundary 之前连续 LayerGroup 前缀作为 Static Underlay。
|
||
- boundary 及之后继续实时绘制。
|
||
- 没有 boundary 时完全保持原 Renderer。
|
||
|
||
Layer 顺序、parameters.currentLayer、depthRangeSize、opaque/translucent 原始 ordinal 必须保持，不允许对子集从 0 重新编号而改变透明/depth 语义。
|
||
|
||
## 4. Static Underlay Cache
|
||
建议 Renderer-owned helper：
|
||
- src/mbgl/renderer/retained_underlay_cache.hpp
|
||
- src/mbgl/renderer/retained_underlay_cache.cpp
|
||
|
||
职责：
|
||
- offscreen renderable / texture
|
||
- viewport size
|
||
- boundary
|
||
- valid/invalid
|
||
- invalidation reason
|
||
- build/reuse/fallback 计数
|
||
- compositor resources
|
||
|
||
不改变 Heatmap/Hillshade RenderTarget 现有行为；复用现有 gfx::OffscreenTexture / RenderTarget / Drawable / shader abstraction。
|
||
|
||
## 5. Texture Composite
|
||
使用独立语义的 RetainedUnderlayCompositeShader：
|
||
- viewport/fullscreen quad
|
||
- sample cached RGBA texture
|
||
- 正确 premultiplied alpha
|
||
- 不做 map transform / color ramp / Particle 业务
|
||
|
||
不要长期复用 LocationIndicatorTexturedShader。
|
||
|
||
## 6. STEP-088
|
||
先只消除静态地图重复 GPU draw，仍保留：
|
||
- Map::Impl::onUpdate
|
||
- UpdateParameters
|
||
- createRenderTree
|
||
- source update / TilePyramid update
|
||
- source/layer prepare
|
||
- updateLayers
|
||
- LayerGroup tweaker/upload
|
||
|
||
Render 阶段：
|
||
1. cache invalid：boundary 前 LayerGroups render 到 offscreen。
|
||
2. cache valid：跳过 boundary 前静态 draw。
|
||
3. main framebuffer clear。
|
||
4. composite cached underlay。
|
||
5. boundary 及之后 WeatherColor/Particle/动态 overlay 正常绘制。
|
||
6. present。
|
||
|
||
## 7. STEP-089
|
||
在 STEP-088 实机通过后再做 production invalidation：
|
||
- Camera center/zoom/bearing/pitch
|
||
- viewport/pixelRatio
|
||
- style/layer add/remove/reorder/change
|
||
- source/tile/bucket/drawable 变化
|
||
- sprite/image/glyph
|
||
- symbol placement/fade
|
||
- context/surface recreation
|
||
- 3D/terrain/custom/debug fallback
|
||
- OpenGL/Metal 一致生命周期
|
||
|
||
## 8. STEP-090 条件步骤
|
||
只有 STEP-089 后真实 NavSea profile 仍证明主要 CPU 落在：
|
||
- Map::Impl::onUpdate
|
||
- createRenderTree
|
||
- Vector/PBF source update
|
||
- TilePyramid update
|
||
- source/layer prepare
|
||
才进入 Animation-only fast path。
|
||
|
||
如果 STEP-089 已满足性能目标，不执行 STEP-090。
|
||
|
||
## 9. STEP-088 安全边界
|
||
PoC reuse 至少要求：
|
||
- 2D
|
||
- Camera fingerprint 连续一致
|
||
- viewport 不变
|
||
- style loaded
|
||
- boundary 不变
|
||
- context/resource 正常
|
||
|
||
以下至少 fallback full render：
|
||
- has3D
|
||
- Debug Overdraw
|
||
- cache texture/compositor 创建失败
|
||
- viewport resize
|
||
- boundary change
|
||
- context 不可用
|
||
- legacy RenderItem ordering 无法证明安全
|
||
- 其他不能证明 cache 正确的状态
|
||
|
||
原则：不确定就 full render，不用 stale cache 换性能。
|
||
|
||
## 10. 观测
|
||
复用 include/mbgl/particle/renderer_debug_counters.hpp，建议增加：
|
||
- FullRendererFrame
|
||
- RetainedUnderlayBuild
|
||
- RetainedUnderlayReuse
|
||
- RetainedUnderlayFallback
|
||
- RetainedUnderlayInvalidation
|
||
- RetainedUnderlayStaticGroupDraw
|
||
- RetainedDynamicGroupDraw
|
||
|
||
固定 Camera + Particle 约 30 FPS 时，理想：
|
||
- RetainedUnderlayBuild ≈ 1
|
||
- RetainedUnderlayReuse 持续增长
|
||
- ParticleSimulationAdvance 持续增长
|
||
- StaticGroupDraw 建 cache 后不随 Particle FPS 增长
|
||
- DynamicGroupDraw 持续增长
|
||
|
||
## 11. 不允许
|
||
- React RAF 驱动
|
||
- Host renderFastFrame/cacheMapNow/invalidateBasemap API
|
||
- NavSea 手工管理 renderer cache
|
||
- 修改 C-001
|
||
- 永久 public static/dynamic flag
|
||
- 改变 Style layer ordering
|
||
- STEP-088 就跳过 source/update/prepare
|
||
- Android/iOS 不同 renderer semantics
|
||
- stale cache
|
||
|
||
## 12. 执行顺序
|
||
1. STEP-088：PoC + observability
|
||
2. 用户 Android/NavSea 真机验证
|
||
3. STEP-089：production invalidation/fallback
|
||
4. 用户再次 profile
|
||
5. 只有 CPU orchestration 仍是瓶颈时才 STEP-090
|