MapLibreParticleLab/docs/50_Step记录/STEP-058_WeatherLocalTargetFps与RepaintGate_v1.md

STEP-058 Weather-local Target FPS 与 Repaint Gate

状态：IMPLEMENTED / WAITING_ANDROID_VALIDATION

Starting HEAD：6d514e3aae68f579af41b10f85efe0f3b28784b2，分支 particle/main。

目标

为天气粒子与 WeatherColor 建立 source-local AUTO/30/60 cadence 和 repaint gate，不限制全局 Map FPS，不进入 React Native package。

已完成

• WeatherRuntime.TargetFps、setTargetFps()、getTargetFps() typed Host API，经 MapLibreMap → NativeMapView → JNI → RasterArraySource 接线。
• RasterArrayTimelineRuntime 持有单一 target/deadline authority；Particle 与 WeatherColor 共用 due 判定，真实 steady_clock elapsed 驱动 Timeline、particle lifecycle 与 Trail fade。
• 未到 deadline 的地图高频帧不推进天气 State/Trail/Timeline；Android facade 使用既有 triggerRepaint() 低频 delayed wake-up，不调用全局 setMaximumFps()。
• REAL WEATHER popup 增加 FPS AUTO/30/60，HUD 显示当前选择；两层 visibility、PLAY/PAUSE、clear/disabled 的持续 wake-up 规则已收敛。
• 增加 deterministic cadence 测试，覆盖 AUTO、30/60 deadline、target 切换与单 authority。

保护与禁止范围

canonical field、field bytes、submit result、timestamp、playback、WeatherColor ramp、particle/trail color、OFF unload、hidden cleanup、Runtime Field Window、OLD_T1→NEW_T0 reuse、only NEW_T1 upload、simulation/trail reset 保护均未重写；未新增 RN/provider/route/ETA/Jest，也未使用全局 Map FPS cap。

验证

• throttle 下 Linux/OpenGL mbgl-test-runner 与 mbgl-render-test-runner 增量构建：PASS。
• throttle 下 deterministic cadence 测试 Source.RasterArrayTimelineCadenceUsesOneSharedDeterministicDeadline：PASS。
• throttle 下 Source.RasterArray* 定向测试：PASS。
• git diff --check：PASS。
• 未执行 Android Gradle、APK、ADB、设备/虚拟机测试或 Jest。

剩余风险

Android JNI/Java compile 与设备上 30/60 tick、camera 并发、visibility/off wake-up 仍需统一人工验收；天气 camera skipped-frame composite 的具体 GPU 视觉连续性需实机确认。

STEP-058A Shared Cadence 与 WeatherRuntime 生命周期修正

状态：IMPLEMENTED / WAITING_ANDROID_VALIDATION。

• 以 RasterArrayTimelineRuntime::advanceIfDue() 取代 renderer 单独 tick()，在 timeline 锁内原子完成 deadline claim、revision 标记和 wall-time 推进。WeatherColor-only + PLAY 可独立推进 MIX；同一 deadline Particle 后到仅消费相同 frame/revision，不会双推进。
• WeatherColor-only + PAUSE 不主动持续 repaint；Particle visible + PAUSE 保持粒子 cadence；两层 hidden、clear/disable 不再由 facade 保留 delayed wake-up。
• 新增幂等 WeatherRuntime.dispose()；disposed 后取消 callback、旧 Runnable 不 repaint/不重排，控制 API 拒绝或 fail-fast。Test App 在 style reload、leave REAL WEATHER、Activity destroy 前显式释放旧 Runtime。
• Linux/OpenGL 增量 build、Source.RasterArray* deterministic/source 定向测试和 git diff --check 通过；Android Gradle/APK/ADB/设备/Jest 未执行。