MapLibreParticleLab/docs/报告/STEP-058_WeatherLocalTargetFps与RepaintGate_Codex完成报告_v1.md

STEP-058 Weather-local Target FPS 与 Repaint Gate — Codex 完成报告

状态：IMPLEMENTED / WAITING_ANDROID_VALIDATION

实际完成

• WeatherRuntime 新增 typed TargetFps.AUTO/FPS_30/FPS_60、setTargetFps()、getTargetFps()。
• 接通 MapLibreMap → NativeMapView → JNI → RasterArraySource；Core RasterArrayTimelineRuntime 作为 Particle/WeatherColor 共用 cadence authority，保存 target、deadline 与低频 tick 计数。
• needsRepaint() 与 timeline due gate 统一；未到 deadline 时不推进 Timeline、State、Trail 或 field upload，camera frame 可重用已有 composite。
• Android facade 仅使用已有 triggerRepaint() 做 delayed wake-up，不使用 MapView#setMaximumFps() 或 Android 高频 polling。
• REAL WEATHER tuning popup 增加 FPS AUTO/30/60，HUD 显示当前 target；target 切换不 reload Style、resubmit field、reset simulation/Trail 或重建 field texture。
• 增加 deterministic non-sleep cadence 测试与 source 定向覆盖。

修改文件

• include/mbgl/style/sources/raster_array_source.hpp
• src/mbgl/style/sources/raster_array_source.cpp
• src/mbgl/renderer/layers/render_particle_validation_layer.cpp
• src/mbgl/renderer/layers/render_weather_color_layer.cpp
• platform/android/MapLibreAndroid/src/cpp/native_map_view.hpp
• platform/android/MapLibreAndroid/src/cpp/native_map_view.cpp
• platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/NativeMap.java
• platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/NativeMapView.java
• platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/MapLibreMap.java
• platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/WeatherRuntime.java
• platform/android/MapLibreAndroid/src/test/java/org/maplibre/android/maps/WeatherRuntimeStateTest.java
• platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/particle/ParticleCoreLayerValidationActivity.kt
• test/style/source.test.cpp
• docs/30_设计/STEP-058_WeatherLocalTargetFps与RepaintGate设计_v1.md
• docs/50_Step记录/STEP-058_WeatherLocalTargetFps与RepaintGate_v1.md
• 粒子开发记录.md

验证

• ninja -C build-linux-opengl mbgl-test-runner mbgl-render-test-runner（经 build-output-throttle）：PASS。
• mbgl-test-runner --gtest_filter='Source.RasterArrayTimelineCadenceUsesOneSharedDeterministicDeadline'（经 throttle）：PASS。
• mbgl-test-runner --gtest_filter='Source.RasterArray*'（经 throttle）：PASS。
• git diff --check：PASS。

未执行 Android Gradle/APK、ADB、设备/虚拟机测试或 Jest。

设计边界与风险

天气 cadence 绑定 Source-owned timeline，未改变 canonical/T0/T1/MIX、Runtime Field Window、OLD_T1→NEW_T0 reuse、only NEW_T1 upload、simulation/trail reset 语义。Android delayed wake-up 与 JNI/Java compile、camera skipped-frame 的实际视觉连续性仍需人工验收；本报告不宣称 Android validated。

Git

• Starting HEAD：6d514e3aae68f579af41b10f85efe0f3b28784b2
• 功能 commit：b9b3dd22530759129b8c80477409bb7e5df4f4cc
• 功能 commit message：feat: add weather-local render cadence
• 文档 commit：8a74a3c24e8ad59caee25bd9b5338d26d4b62039
• Push：成功（功能与文档提交已推送）
• Remote branch：origin/particle/main
• 功能/文档主体 Final HEAD：8a74a3c24e8ad59caee25bd9b5338d26d4b62039

本报告元数据收尾提交及其最终分支 HEAD 在交付消息中列出；收尾提交不改变功能代码。