4.6 KiB
STEP-057 Android Host 天气运行时接口基础 — Codex 完成报告
状态
IMPLEMENTED / WAITING_ANDROID_VALIDATION。
- Starting HEAD：
faf7548220e9a1282275711c236987f7faedfa03 - 功能提交：
a81b464d9b6381ae5b2fb953358d25c20d62bb78—feat: add Android host weather runtime facade - 文档提交：本报告所在提交
- Final HEAD / origin/particle/main：在文档提交并 push 后记录于交付结果。
实际完成内容与 API
新增 org.maplibre.android.maps.WeatherRuntime，以 Config(sourceId, weatherColorLayerId, particleLayerId) 作为唯一 Host 绑定。公开方法为 submitWindField、clearWindFields、setWeatherEnabled、两个 visibility setter、setForecastTime、play/pause/speed、WeatherColor opacity、particle visual、setWeatherColorStops、setParticleColors 和 getState。
FieldSubmitResult 逐一映射现有 Core result，CommandResult 和 State(DISABLED/WAITING_FOR_FIELDS/READY/ERROR) 供未来 RN 薄包装读取；无 per-frame callback。Host 不得到 T0/T1、MIX、State/Trail、纹理或 renderer resource。
Android → JNI → C++ 新接线为：visibility、particle/trail RGBA、WeatherColor stop arrays，以及既有 submit/clear/timestamp/timeline command。Test App 的 REAL WEATHER 提交和基础播放控制已走 facade。
clearWindFields 清除 pending T0、Timeline、authoritative window 与 Source snapshots。setWeatherEnabled(false) 暂停、隐藏两层、clear fields；渲染线程的空 Source path 清理 particle State/Trail/draw、field textures、WeatherColor resources，保留 Source/Layer 以支持 ON 后重新提交。日志包含 TIMELINE_STOP、FIELD_WINDOW_CLEAR、SNAPSHOT_CLEAR 与三类 resource release。
WeatherColor ramp 最多 8 stop，要求 2 个以上、speed finite 严格递增、RGBA 为有限 [0,1]；无效更新 reject 且保留上一有效 ramp。UBO 实现低频更新，不上传 wind field。particleColor 和 trailColor 为独立 UBO 属性；不读取 WeatherColor ramp。legacy speed color 只在显式开启时影响当前粒子 segment。
timestamp 恰好 T0、T1 和中间值均由 Core 选择相邻快照和 MIX；中间插值。超范围、空 timeline、Gap/Invalid 返回 reject。window 未切换的 seek 不增加 revision，因而不造成 field upload、simulation rebuild 或 trail clear；跨窗口仍走 OLD_T1→NEW_T0 reuse。
修改文件
功能修改覆盖 Android Java facade/NativeMap/JNI、RasterArraySource Timeline、WeatherColor/RasterParticle style model、particle UBO/shader、两个 renderer、RenderOrchestrator、REAL WEATHER Test App 以及 test/style/source.test.cpp、test/style/style_layer.test.cpp。完整逐文件清单可由功能提交取得；接口契约见 docs/30_设计/STEP-057_AndroidHost天气运行时接口契约_v1.md。
本地验证
node shaders/generate_shader_code.mjs -o .：PASS。ninja -C build-linux-opengl -j3 mbgl-core：PASS。ninja -C build-linux-opengl -j3 test/CMakeFiles/mbgl-test.dir/style/style_layer.test.cpp.o test/CMakeFiles/mbgl-test.dir/style/source.test.cpp.o：PASS。build-linux-opengl/mbgl-test-runner --gtest_filter='Source.HostFieldClearAndTimestampSeekAreFailClosed:Layer.RasterParticleVisualProperties:Layer.WeatherColorUsesIndependentFixedOpacity'：PASS。git diff --check：PASS。
所有 build/codegen/test 命令均通过 ~/.codex/AGENTS.md 要求的 output-throttle wrapper 执行；日志保存在本机 /tmp/step057-logs/，不纳入提交。
未执行与风险
Android Gradle：NOT RUN。APK build：NOT RUN。ADB：NOT RUN。Android device validation：NOT RUN。Jest：NOT RUN。
Linux OpenGL 不能证明 Android OpenGL/Vulkan JNI/GLSL runtime 行为；Android 手工验收需确认 OFF 后三个 release 日志、连续 ON/OFF 内存、动态 ramp/particle/trail color 无 field upload 或 reset、timestamp 中点、playback 和 T0/T1 window boundary 的 zero-reset 保护。
建议手工命令（设备固定为 192.168.1.146）：
cd platform/android && RENDERER=opengl BUILDTYPE=Debug make apackage
# APK: platform/android/MapLibreAndroidTestApp/build/outputs/apk/debug/MapLibreAndroidTestApp-debug.apk
adb -s 192.168.1.146 install -r MapLibreAndroidTestApp/build/outputs/apk/debug/MapLibreAndroidTestApp-debug.apk
adb -s 192.168.1.146 shell am start -n org.maplibre.android.testapp/.activity.particle.ParticleCoreLayerValidationActivity
adb -s 192.168.1.146 logcat -v time | grep -E 'WeatherRuntime|ParticleTimeline|ParticleGPU|WeatherColorLayer'
Windows 安装同样使用：adb -s 192.168.1.146 install -r <Windows 上实际生成的 MapLibreAndroidTestApp-debug.apk>；使用同一显式设备序列号。