# 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。