MapLibreParticleLab/docs/30_设计/STEP-057_AndroidHost天气运行时接口契约_v1.md

STEP-057 Android Host 天气运行时接口契约

入口与线程

公开入口为 org.maplibre.android.maps.WeatherRuntime，由 Android 主线程创建和调用。MapLibreMap 同样要求主线程访问；本 facade 不创建 Timer、线程或 per-frame Java 回调。Core 继续在其既有 Map/Render 线程完成 Timeline、窗口和 GPU 工作。

WeatherRuntime.Config(sourceId, weatherColorLayerId, particleLayerId) 绑定一个已存在的 style runtime；ID 不可为空，未硬编码 Test App ID。

API

• submitWindField(metadataJson, byte[]) -> FieldSubmitResult：复用 canonical ingress。结果逐一映射 REJECTED_*、ACCEPTED_PENDING_INITIAL_WINDOW、INITIAL_WINDOW_READY、ACCEPTED_NEXT_SNAPSHOT、DUPLICATE。
• clearWindFields() -> CommandResult：暂停 Timeline，清除 pending T0、Timeline entries、authoritative T0/T1 和 retained snapshots；Source/Layer 可复用。
• setWeatherEnabled(boolean)：OFF 暂停、隐藏两层并 clear fields；Render 线程发现空场时释放粒子 State/Trail/draw、field texture 和 WeatherColor 资源。ON 只恢复 visibility，状态为 WAITING_FOR_FIELDS，必须重新提交 T0/T1。
• setWeatherColorVisible / setParticleVisible：仅 visibility，hide != unload。
• setForecastTime(timestampMs)：Core 按 timestamp 选相邻 T0/T1 并计算 MIX。恰好命中末快照为 MIX=1；中间线性插值；超范围、未 READY、Gap/Invalid 返回 REJECTED，不会沿用错误旧时间。正常 seek 不 submit field、不 reset particle、不 clear trail；仅跨窗口时沿用既有 OLD_T1→NEW_T0 reuse。
• setPlaybackState(PLAY/PAUSE)、setPlaybackSpeed(HALF/NORMAL/DOUBLE)：复用 Source Timeline，不创建 Android Timer。
• setWeatherColorOpacity、setParticleCount、setParticleLineWidth、setParticleLength、setParticleOpacity、setTrailOpacity、setTrailFade、setParticleSpeedColorEnabled：明确 typed 的低频 visual 更新；正式 Host API 不接收 property string。
• setWeatherColorStops(List<ColorStop>)：2 至 Core MaxWeatherColorStops 个 stop（v1 为 8，Java 经 JNI getWeatherColorStopCapacity() 获取），speed finite 严格递增，RGBA 均为有限 [0,1]。低于/高于边界分别钳到首/末颜色，中间线性插值。无效输入 reject，并保留上一套有效 ramp。
• setParticleColors(...)：独立 particle/trail RGBA；不依赖 WeatherColor ramp。legacy speed-color-enabled=true 时仅当前 segment 可使用旧 speed 色，不改变 WeatherColor stops。

状态为 DISABLED、WAITING_FOR_FIELDS、READY、ERROR，仅由低频命令和 submit result 更新。v1 提供同步 typed result/state query；没有 listener，未来 RN 薄层可在这些调用完成后读取结果。

JNI 与边界

Java facade 经 MapLibreMap / NativeMapView 到 JNI：field submit、clear、timestamp seek、Timeline command、layer visibility、particle/trail colour、WeatherColor stops。C++ Renderer 不接触 provider、HTTP、route、ETA 或预测目录；没有向 Host 暴露 T0/T1、MIX、State A/B、Trail A/B、资源代际或 texture 格式。

Shader-visible ramp 是 UBO 的 8 个 stop/颜色槽；改 ramp 不上传 Field，也不重建粒子 simulation。粒子/尾迹颜色也只更新 UBO。