3.9 KiB
STEP-085 V4 Renderer 性能修复设计 v1
状态：IMPLEMENTED / WAITING_FOR_RDC_NATIVE_BUILD
目标与根因
V4 的 RasterArraySource 通过独立的 field-keyed window 产出已经 materialize 的 T0/T1/MIX。旧 renderer 将 V4 误当作“没有 timeline”，从而产生两项错误：WeatherColor 的 needsRepaint() 永远为 true；Particle 也永远请求下一帧，并在 prepare() 将包含大 vector/scalar/valid 数组的 snapshot 按值复制。
本设计保持 V3 timeline、V4 Runtime Field Window、QBIN 和所有 RN/Host 公共接口不变，只在 Source 内部和共用 renderer seam 修复 cadence/lifetime。
共用 cadence 语义
新增 Source-owned RasterArrayRendererCadence。它只负责 visual simulation 的 deadline，不携带 field、不会变更 T0/T1/MIX，也不会调用 ForecastClock。
| targetFps | Core cadence | platform wake |
|---|---|---|
| AUTO | 每个 MapLibre animation frame 可消费一次 | 沿用平台 animation-frame 语义 |
| 30 | 约 33.3ms 才允许一次 simulation | Android Handler / iOS NSTimer 约 34ms 请求一次 repaint |
| 60 | 约 16.7ms 才允许一次 simulation | Android Handler / iOS NSTimer 约 17ms 请求一次 repaint |
RenderRasterParticleLayer::needsRepaint() 仅对 active、visible、field-ready 的 V4 Particle 在 deadline 到期时返回 true。因 camera 而来的额外 frame 仍可 composite 当前 trail，但 consumeIfDue() 未成功时不建 State/Trail pass、不推进 ping-pong、不衰减 trail。Forecast PAUSE 不影响该 visual cadence。
Android/iOS runtime timer 仅是已有 facade 的“下一帧 wake”薄层；deadline 与是否推进由共用 C++ Source cadence 判定。hidden、clear、disable 和 dispose 都停止 V4 Particle wake。
WeatherColor idle 与 drawable
V4 WeatherColor 在 PAUSE、field/window/stops/opacity/transform 不变时 needsRepaint()==false。它不再以 sourceTimeline == nullptr 作为“永远动画”的代理。
稳定状态下 WeatherColor drawable 复用既有 LayerGroup drawable。T0/T1 texture、mix、opacity、color stops 与 value source 由 Resources/Tweaker 在 render 时更新 UBO；仅 wrap 集合变化才 clearDrawables() 后重建。该方案保留 gfx abstraction，未引入 OpenGL/Metal 直接调用。
V4 snapshot lifetime
materialize 仍发生在 Source 的 binding/window 真正变化时，但 Materialized*Projection 与 renderer sourceField/sourceNextField 全部改为 shared_ptr<const ParticleFieldSnapshot>。Source Impl 的不可变副本持有 projection，RenderLayer 只复制 shared handle；稳定 window 的 prepare() 不再深复制 scalar/vector/valid arrays。旧 V3 optional snapshot 路径仍在 Source 变化时构造独立 handle，未改变其 API。
Debug/Validation observability
include/mbgl/particle/renderer_debug_counters.hpp 在非 release 建立低成本 relaxed atomic 累计器，release 编译为 no-op。覆盖：两 layer 的 needsRepaint/update、particle simulation advance、WeatherColor/Particle drawable rebuild、field texture upload、GPU resource create/release-reset、trail create/resize、V4 projection materialize 与 field-window revision。它不逐帧写普通日志，也不暴露给 NavSea。
ForecastClock 审查
全仓确认 RasterArraySource::advanceForecastClock(elapsedMs) 只有定义，当前 Android WeatherRuntime、iOS MLNParticleFieldRuntime 与 RN bridge 均没有 production caller。故 V4 PLAY 自动推进尚无 owner；本 Step 不将 cadence timer 偷接成第二个 forecast clock。Host 显式 setEncodedForecastTime 继续触发 window refresh；自动 forecast playback 应单独设计 owner 后处理。
生命周期边界
本 Step 不改变 detach()、dispose、Host clear/destroy contract，也不对 retained allocation/Native Heap 归因。计数器和减少 repaint/copy/rebuild 仅为后续 RDC 采样提供证据。