From dad6876c72f29e2d5671677ee15e13cd25e653a1 Mon Sep 17 00:00:00 2001 From: OpenAI Codex Date: Mon, 7 Sep 2026 11:42:28 +0800 Subject: [PATCH] fix: audit STEP-057 weather runtime facade --- ...STEP-057_AndroidHost天气运行时接口契约_v1.md | 4 +- ...STEP-057_AndroidHost天气运行时接口基础_v1.md | 12 ++++++ ...idHost天气运行时接口基础_Codex完成报告_v2.md | 34 +++++++++++++++ .../src/cpp/native_map_view.cpp | 5 +++ .../src/cpp/native_map_view.hpp | 1 + .../maplibre/android/maps/MapLibreMap.java | 5 +++ .../org/maplibre/android/maps/NativeMap.java | 2 + .../maplibre/android/maps/NativeMapView.java | 5 +++ .../maplibre/android/maps/WeatherRuntime.java | 41 +++++++++++++++---- .../android/maps/WeatherRuntimeStateTest.java | 23 +++++++++++ .../ParticleCoreLayerValidationActivity.kt | 16 +++++++- .../render_particle_validation_layer.cpp | 7 ++++ .../layers/render_raster_particle_layer.hpp | 1 + .../layers/render_weather_color_layer.cpp | 6 +++ .../layers/render_weather_color_layer.hpp | 1 + src/mbgl/renderer/render_layer.hpp | 4 ++ src/mbgl/renderer/render_orchestrator.cpp | 8 ++-- test/style/source.test.cpp | 21 ++++++---- test/style/style_layer.test.cpp | 3 ++ 粒子开发记录.md | 7 ++++ 20 files changed, 183 insertions(+), 23 deletions(-) create mode 100644 docs/报告/STEP-057_AndroidHost天气运行时接口基础_Codex完成报告_v2.md create mode 100644 platform/android/MapLibreAndroid/src/test/java/org/maplibre/android/maps/WeatherRuntimeStateTest.java diff --git a/docs/30_设计/STEP-057_AndroidHost天气运行时接口契约_v1.md b/docs/30_设计/STEP-057_AndroidHost天气运行时接口契约_v1.md index 7cbe7a738..75899eee2 100644 --- a/docs/30_设计/STEP-057_AndroidHost天气运行时接口契约_v1.md +++ b/docs/30_设计/STEP-057_AndroidHost天气运行时接口契约_v1.md @@ -14,8 +14,8 @@ - `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`、`setParticleVisual`：低频 visual 更新。 -- `setWeatherColorStops(List)`：2 至 8 个 stop，speed finite 严格递增，RGBA 均为有限 [0,1]。低于/高于边界分别钳到首/末颜色，中间线性插值。无效输入 reject，并保留上一套有效 ramp。 +- `setWeatherColorOpacity`、`setParticleCount`、`setParticleLineWidth`、`setParticleLength`、`setParticleOpacity`、`setTrailOpacity`、`setTrailFade`、`setParticleSpeedColorEnabled`：明确 typed 的低频 visual 更新；正式 Host API 不接收 property string。 +- `setWeatherColorStops(List)`：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 薄层可在这些调用完成后读取结果。 diff --git a/docs/50_Step记录/STEP-057_AndroidHost天气运行时接口基础_v1.md b/docs/50_Step记录/STEP-057_AndroidHost天气运行时接口基础_v1.md index 231b1378b..4b3777a2d 100644 --- a/docs/50_Step记录/STEP-057_AndroidHost天气运行时接口基础_v1.md +++ b/docs/50_Step记录/STEP-057_AndroidHost天气运行时接口基础_v1.md @@ -13,3 +13,15 @@ OFF 会停止 Timeline、clear Host ownership，并在 Render 线程的空 Sourc 本地验证：shader generator、Linux OpenGL `mbgl-core`、`style_layer.test.cpp` 与 `source.test.cpp` 精确编译；`git diff --check`。Android Gradle/APK/ADB/设备测试和 Jest 未运行。 未完成：Android 手工 T1–T13 验收，特别是 OFF resource log、ON 后重新 T0/T1、dynamic ramp/colour 无 field upload/particle reset、timestamp mid-point 和窗口边界回归。 + +## STEP-057A 审计修正（2026-09-07） + +状态保持 `IMPLEMENTED / WAITING_ANDROID_VALIDATION`。基于已推送 `efaa3e61c` 审计修正，不进入 STEP-058。 + +- 删除正式 `WeatherRuntime.setParticleVisual(String, float)`；改为 particle count、line width、length、particle/trail opacity、trail fade、speed-color enabled 的明确 typed 方法。Test App 的 fixture-only generic property 调试仍只留在低层路径。 +- 修正 facade 状态：READY 重复 enable 幂等；DISABLED enable 进入 WAITING；ERROR 收到 pending T0 恢复 WAITING；initial window ready 进入 READY；clear/disable 只在对应 Core 成功时转入 WAITING/DISABLED。新增 Android 既有 JUnit state transition 定向测试源码，未按本轮限制执行 Gradle。 +- `RenderOrchestrator` 不再对所有 hidden RasterArray layer 执行额外 prepare/update。`RenderLayer` 默认无 cleanup；仅仍持有资源、Host-field Source 已空的 RasterParticle/WeatherColor renderer 显式 opt-in，完成一次空场 GPU cleanup。普通 hidden layer 语义不变。 +- Host stop capacity 改为由 JNI 读取 Core `MaxWeatherColorStops`；Host API 继续接受 `ColorStop` list，未暴露 UBO。严格验证与 particle/trail 独立性保持。 +- timestamp 测试改为 epoch milliseconds（2024-01-01 UTC 起的 64-bit ms），覆盖 exact T0、midpoint、exact T1、上下界 out-of-range 与 clear 后 fail-closed。 + +验证：output-throttle 下 shader generator、Linux OpenGL `mbgl-core`、`mbgl-render`、`mbgl-test-runner`、相关精确 Source/Style compile 和定向非 Jest tests 均 PASS；`git diff --check` PASS。Android Gradle/APK/ADB/设备/Jest 未运行。 diff --git a/docs/报告/STEP-057_AndroidHost天气运行时接口基础_Codex完成报告_v2.md b/docs/报告/STEP-057_AndroidHost天气运行时接口基础_Codex完成报告_v2.md new file mode 100644 index 000000000..86b346a2f --- /dev/null +++ b/docs/报告/STEP-057_AndroidHost天气运行时接口基础_Codex完成报告_v2.md @@ -0,0 +1,34 @@ +# STEP-057A Android Host 天气运行时接口审计修正 — Codex 完成报告 + +状态：`IMPLEMENTED / WAITING_ANDROID_VALIDATION`。本轮仅修正 STEP-057，不进入 STEP-058、React Native bridge 或性能任务。 + +## 实际修正 + +1. `WeatherRuntime` 删除公开 `setParticleVisual(String, float)`。正式 API 改为 `setParticleCount`、`setParticleLineWidth`、`setParticleLength`、`setParticleOpacity`、`setTrailOpacity`、`setTrailFade`、`setParticleSpeedColorEnabled`；Core property 语义未改。Test App 的未映射 fixture diagnostic 才可使用低层 generic setter。 +2. 状态转换被收敛为可单测函数：READY enable 幂等；DISABLED 成功 enable → WAITING；ERROR 成功 pending field → WAITING；initial window ready/next snapshot → READY；成功 clear → WAITING；成功 disable → DISABLED。新增 `WeatherRuntimeStateTest`，使用现有 Android JUnit 体系；遵从任务限制未运行 Gradle。 +3. 取消 `RenderOrchestrator` 的所有 hidden RasterArray 层全局 prepare/update。新增默认关闭的 `RenderLayer::needsHiddenLayerSourceCleanup`；只有持有 GPU resource 且 Host-field source 已清空的 RasterParticle/WeatherColor layers opt-in，才在 hidden 时接收一轮 cleanup。普通 hidden MapLibre layer 生命周期不变。 +4. stop 上限继续由 C++ `MaxWeatherColorStops=8` 定义。Java 经 JNI 获取 capacity，facade 以 `ColorStop` list 验证，不暴露 UBO 数组。严格 speed/RGBA 校验和独立 particle/trail color 保持。 +5. Source timestamp tests 现在使用 epoch milliseconds：T0=`1704067200000`、T1=`1704070800000`，验证 exact T0、midpoint、exact T1、lower/upper out-of-range 与 clear 后 fail-closed。 + +既有 clear/unload、JNI、Core-owned T0/T1/MIX、dynamic ramp、独立颜色、field/window reuse、无 style reload 均保留。正常 window boundary 的 OLD_T1→NEW_T0 / only NEW_T1 upload 路径未改；本轮没有触及 simulation/trail reset 条件。 + +## 验证 + +所有编译、codegen 和测试均经 `build-output-throttle` wrapper，日志仅存 `/tmp/step057a-logs/`，未提交。 + +- shader generator：PASS。 +- Linux OpenGL `mbgl-core`：PASS。 +- Linux OpenGL `mbgl-render`：PASS。 +- Linux OpenGL `mbgl-test-runner`：PASS。 +- `style_layer.test.cpp` / `source.test.cpp` 精确编译：PASS。 +- 定向非 Jest tests（timestamp seek、clear、WeatherColor stop validation、particle/trail properties）：PASS。 +- `git diff --check`：PASS。 + +未执行：Android Gradle、APK build、ADB、Android device validation、Jest。 + +## Git + +- 审计起点：`efaa3e61c94e056bf06a955eb250cdfdc1633ecd` +- 功能提交、文档提交、push 和 Final HEAD：在完成提交后以最终交付结果为准。 + +Android 后续人工验收仍需重点检查 OFF hidden cleanup logs、READY 重复 ON、ERROR→pending→WAITING、dynamic stop/colour 无 field upload/reset、epoch-ms seek 与正常 window boundary `simulationRebuild=false` / `trailCleared=false`。 diff --git a/platform/android/MapLibreAndroid/src/cpp/native_map_view.cpp b/platform/android/MapLibreAndroid/src/cpp/native_map_view.cpp index f728c4684..3760938ee 100644 --- a/platform/android/MapLibreAndroid/src/cpp/native_map_view.cpp +++ b/platform/android/MapLibreAndroid/src/cpp/native_map_view.cpp @@ -1214,6 +1214,10 @@ jni::jboolean NativeMapView::setWeatherColorStops(JNIEnv& env, return layer->setColorStops(std::move(stops)); } +jni::jint NativeMapView::getWeatherColorStopCapacity(JNIEnv&) { + return static_cast(mbgl::style::MaxWeatherColorStops); +} + jni::jboolean NativeMapView::advanceRasterArraySourceFieldWindow(JNIEnv& env, const jni::String& sourceId) { const auto id = jni::Make(env, sourceId); auto* source = map->getStyle().getSource(id); @@ -1692,6 +1696,7 @@ void NativeMapView::registerNative(jni::JNIEnv& env) { METHOD(&NativeMapView::setStyleLayerVisibility, "nativeSetStyleLayerVisibility"), METHOD(&NativeMapView::setRasterParticleColors, "nativeSetRasterParticleColors"), METHOD(&NativeMapView::setWeatherColorStops, "nativeSetWeatherColorStops"), + METHOD(&NativeMapView::getWeatherColorStopCapacity, "nativeGetWeatherColorStopCapacity"), METHOD(&NativeMapView::advanceRasterArraySourceFieldWindow, "nativeAdvanceRasterArraySourceFieldWindow"), METHOD(&NativeMapView::repeatRasterArraySourceFieldWindow, "nativeRepeatRasterArraySourceFieldWindow"), METHOD(&NativeMapView::submitRasterArraySourceHostField, "nativeSubmitRasterArraySourceHostField"), diff --git a/platform/android/MapLibreAndroid/src/cpp/native_map_view.hpp b/platform/android/MapLibreAndroid/src/cpp/native_map_view.hpp index 67960770d..7095ee621 100644 --- a/platform/android/MapLibreAndroid/src/cpp/native_map_view.hpp +++ b/platform/android/MapLibreAndroid/src/cpp/native_map_view.hpp @@ -285,6 +285,7 @@ public: jni::jboolean setStyleLayerVisibility(JNIEnv&, const jni::String&, jni::jboolean); jni::jboolean setRasterParticleColors(JNIEnv&, const jni::String&, const jni::Array&, const jni::Array&); jni::jboolean setWeatherColorStops(JNIEnv&, const jni::String&, const jni::Array&, const jni::Array&); + jni::jint getWeatherColorStopCapacity(JNIEnv&); jni::jboolean advanceRasterArraySourceFieldWindow(JNIEnv&, const jni::String&); jni::jboolean repeatRasterArraySourceFieldWindow(JNIEnv&, const jni::String&); jni::jint submitRasterArraySourceHostField(JNIEnv&, diff --git a/platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/MapLibreMap.java b/platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/MapLibreMap.java index f1d61c14d..b8bde2abe 100644 --- a/platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/MapLibreMap.java +++ b/platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/MapLibreMap.java @@ -306,6 +306,11 @@ public final class MapLibreMap { return nativeMapView.setWeatherColorStops(layerId, speedsMps, rgbaStops); } + /** Returns the Core-owned WeatherColor stop capacity for typed Host validation. */ + public int getWeatherColorStopCapacity() { + return nativeMapView.getWeatherColorStopCapacity(); + } + /** Advances a Source-owned raster-array runtime Field window without reloading the Style. */ public boolean advanceRasterArraySourceFieldWindow(String sourceId) { return nativeMapView.advanceRasterArraySourceFieldWindow(sourceId); diff --git a/platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/NativeMap.java b/platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/NativeMap.java index 5fb1bced3..b455a29f5 100644 --- a/platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/NativeMap.java +++ b/platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/NativeMap.java @@ -147,6 +147,8 @@ interface NativeMap { boolean setWeatherColorStops(String layerId, float[] speedsMps, float[] rgbaStops); + int getWeatherColorStopCapacity(); + boolean advanceRasterArraySourceFieldWindow(String sourceId); boolean repeatRasterArraySourceFieldWindow(String sourceId); diff --git a/platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/NativeMapView.java b/platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/NativeMapView.java index 511477c96..2729654d1 100755 --- a/platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/NativeMapView.java +++ b/platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/NativeMapView.java @@ -968,6 +968,10 @@ final class NativeMapView implements NativeMap { return !checkState("setWeatherColorStops") && nativeSetWeatherColorStops(layerId, speedsMps, rgbaStops); } + public int getWeatherColorStopCapacity() { + return checkState("getWeatherColorStopCapacity") ? 0 : nativeGetWeatherColorStopCapacity(); + } + @Override public boolean advanceRasterArraySourceFieldWindow(String sourceId) { return !checkState("advanceRasterArraySourceFieldWindow") @@ -1742,6 +1746,7 @@ final class NativeMapView implements NativeMap { @Keep private native boolean nativeSetStyleLayerVisibility(String layerId, boolean visible); @Keep private native boolean nativeSetRasterParticleColors(String layerId, float[] particleColor, float[] trailColor); @Keep private native boolean nativeSetWeatherColorStops(String layerId, float[] speedsMps, float[] rgbaStops); + @Keep private native int nativeGetWeatherColorStopCapacity(); @Keep private native boolean nativeAdvanceRasterArraySourceFieldWindow(String sourceId); diff --git a/platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/WeatherRuntime.java b/platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/WeatherRuntime.java index 689785061..275f49cb8 100644 --- a/platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/WeatherRuntime.java +++ b/platform/android/MapLibreAndroid/src/main/java/org/maplibre/android/maps/WeatherRuntime.java @@ -40,35 +40,41 @@ public final class WeatherRuntime { private final MapLibreMap map; private final Config config; + private final int weatherColorStopCapacity; private State state = State.WAITING_FOR_FIELDS; private boolean weatherColorVisible = true; private boolean particleVisible = true; - public WeatherRuntime(@NonNull MapLibreMap map, @NonNull Config config) { this.map = map; this.config = config; } + public WeatherRuntime(@NonNull MapLibreMap map, @NonNull Config config) { + this.map = map; this.config = config; this.weatherColorStopCapacity = map.getWeatherColorStopCapacity(); + } public State getState() { return state; } public Config getConfig() { return config; } + /** Core-owned capacity; Host never sees the shader's UBO layout. */ + public int getWeatherColorStopCapacity() { return weatherColorStopCapacity; } public FieldSubmitResult submitWindField(@NonNull String metadataJson, @NonNull byte[] payloadBytes) { requireEnabled(); if (metadataJson.isEmpty() || payloadBytes.length == 0) { state = State.ERROR; return FieldSubmitResult.REJECTED_ADAPTER; } FieldSubmitResult result = FieldSubmitResult.fromCode(map.submitRasterArraySourceHostField(config.sourceId, metadataJson, payloadBytes)); - if (result == FieldSubmitResult.INITIAL_WINDOW_READY || result == FieldSubmitResult.ACCEPTED_NEXT_SNAPSHOT || result == FieldSubmitResult.DUPLICATE) state = State.READY; - else if (!result.accepted()) state = State.ERROR; + state = stateAfterSubmit(state, result); return result; } - public CommandResult clearWindFields() { if (state == State.DISABLED) return CommandResult.REJECTED; boolean ok = map.clearRasterArraySourceHostFields(config.sourceId); if (ok) state = State.WAITING_FOR_FIELDS; return result(ok); } + public CommandResult clearWindFields() { if (state == State.DISABLED) return CommandResult.REJECTED; boolean ok = map.clearRasterArraySourceHostFields(config.sourceId); state = stateAfterClear(state, ok); return result(ok); } public CommandResult setWeatherEnabled(boolean enabled) { if (!enabled) { + if (state == State.DISABLED) return CommandResult.ACCEPTED; map.controlRasterArraySourceTimeline(config.sourceId, 1, 0f); boolean color = map.setStyleLayerVisibility(config.weatherColorLayerId, false); boolean particle = map.setStyleLayerVisibility(config.particleLayerId, false); boolean clear = map.clearRasterArraySourceHostFields(config.sourceId); - state = (color && particle && clear) ? State.DISABLED : State.ERROR; + state = stateAfterDisable(color && particle && clear); return result(color && particle && clear); } + if (state != State.DISABLED) return CommandResult.ACCEPTED; boolean color = map.setStyleLayerVisibility(config.weatherColorLayerId, weatherColorVisible); boolean particle = map.setStyleLayerVisibility(config.particleLayerId, particleVisible); - if (color && particle) state = State.WAITING_FOR_FIELDS; else state = State.ERROR; + state = stateAfterEnable(state, color && particle); return result(color && particle); } public CommandResult setWeatherColorVisible(boolean visible) { weatherColorVisible = visible; return result(map.setStyleLayerVisibility(config.weatherColorLayerId, visible && state != State.DISABLED)); } @@ -77,16 +83,35 @@ public final class WeatherRuntime { public CommandResult setPlaybackState(@NonNull PlaybackState playback) { requireEnabled(); return result(map.controlRasterArraySourceTimeline(config.sourceId, playback == PlaybackState.PLAY ? 0 : 1, 0f)); } public CommandResult setPlaybackSpeed(@NonNull PlaybackSpeed speed) { requireEnabled(); return result(map.controlRasterArraySourceTimeline(config.sourceId, 2, speed.value)); } public CommandResult setWeatherColorOpacity(float opacity) { return result(Float.isFinite(opacity) && map.setStyleLayerFloatProperty(config.weatherColorLayerId, "weather-color-opacity", opacity)); } - public CommandResult setParticleVisual(String property, float value) { return result(Float.isFinite(value) && map.setStyleLayerFloatProperty(config.particleLayerId, property, value)); } + public CommandResult setParticleCount(int count) { return setParticleFloat("raster-particle-particle-count", count); } + public CommandResult setParticleLineWidth(float width) { return setParticleFloat("raster-particle-line-width", width); } + public CommandResult setParticleLength(float length) { return setParticleFloat("raster-particle-particle-length", length); } + public CommandResult setParticleOpacity(float opacity) { return setParticleFloat("raster-particle-particle-opacity", opacity); } + public CommandResult setTrailOpacity(float opacity) { return setParticleFloat("raster-particle-trail-opacity", opacity); } + public CommandResult setTrailFade(float fade) { return setParticleFloat("raster-particle-trail-fade", fade); } + public CommandResult setParticleSpeedColorEnabled(boolean enabled) { return setParticleFloat("raster-particle-speed-color-enabled", enabled ? 1f : 0f); } public CommandResult setParticleColors(float red, float green, float blue, float alpha, float trailRed, float trailGreen, float trailBlue, float trailAlpha) { return result(map.setRasterParticleColors(config.particleLayerId, new float[]{red, green, blue, alpha}, new float[]{trailRed, trailGreen, trailBlue, trailAlpha})); } public CommandResult setWeatherColorStops(@NonNull List stops) { - if (stops.size() < 2 || stops.size() > 8) return CommandResult.REJECTED; + if (weatherColorStopCapacity < 2 || stops.size() < 2 || stops.size() > weatherColorStopCapacity) return CommandResult.REJECTED; float[] speeds = new float[stops.size()]; float[] colors = new float[stops.size() * 4]; for (int i = 0; i < stops.size(); i++) { ColorStop stop = stops.get(i); speeds[i] = stop.speedMps; colors[i * 4] = stop.red; colors[i * 4 + 1] = stop.green; colors[i * 4 + 2] = stop.blue; colors[i * 4 + 3] = stop.alpha; } return result(map.setWeatherColorStops(config.weatherColorLayerId, speeds, colors)); } private static CommandResult result(boolean accepted) { return accepted ? CommandResult.ACCEPTED : CommandResult.REJECTED; } + private CommandResult setParticleFloat(String property, float value) { return result(Float.isFinite(value) && map.setStyleLayerFloatProperty(config.particleLayerId, property, value)); } + static State stateAfterSubmit(State current, FieldSubmitResult submit) { + if (submit == FieldSubmitResult.ACCEPTED_PENDING_INITIAL_WINDOW) return State.WAITING_FOR_FIELDS; + if (submit == FieldSubmitResult.INITIAL_WINDOW_READY || submit == FieldSubmitResult.ACCEPTED_NEXT_SNAPSHOT) return State.READY; + if (submit == FieldSubmitResult.DUPLICATE) return current; + return State.ERROR; + } + static State stateAfterClear(State current, boolean accepted) { return accepted ? State.WAITING_FOR_FIELDS : current; } + static State stateAfterDisable(boolean accepted) { return accepted ? State.DISABLED : State.ERROR; } + static State stateAfterEnable(State current, boolean accepted) { + if (!accepted) return State.ERROR; + return current == State.DISABLED ? State.WAITING_FOR_FIELDS : current; + } private void requireEnabled() { if (state == State.DISABLED) throw new IllegalStateException("WeatherRuntime is disabled; enable and submit fields first"); } } diff --git a/platform/android/MapLibreAndroid/src/test/java/org/maplibre/android/maps/WeatherRuntimeStateTest.java b/platform/android/MapLibreAndroid/src/test/java/org/maplibre/android/maps/WeatherRuntimeStateTest.java new file mode 100644 index 000000000..9da45e4ed --- /dev/null +++ b/platform/android/MapLibreAndroid/src/test/java/org/maplibre/android/maps/WeatherRuntimeStateTest.java @@ -0,0 +1,23 @@ +package org.maplibre.android.maps; + +import org.junit.Test; + +import static org.junit.Assert.assertEquals; + +/** Unit coverage for facade-only state transitions; no renderer frame callback is involved. */ +public class WeatherRuntimeStateTest { + @Test public void enableIsIdempotentAndDisabledEnableWaitsForFields() { + assertEquals(WeatherRuntime.State.READY, WeatherRuntime.stateAfterEnable(WeatherRuntime.State.READY, true)); + assertEquals(WeatherRuntime.State.WAITING_FOR_FIELDS, WeatherRuntime.stateAfterEnable(WeatherRuntime.State.DISABLED, true)); + } + @Test public void submitRecoversErrorAndReachesReadyOnlyWithWindow() { + assertEquals(WeatherRuntime.State.WAITING_FOR_FIELDS, WeatherRuntime.stateAfterSubmit(WeatherRuntime.State.ERROR, WeatherRuntime.FieldSubmitResult.ACCEPTED_PENDING_INITIAL_WINDOW)); + assertEquals(WeatherRuntime.State.READY, WeatherRuntime.stateAfterSubmit(WeatherRuntime.State.WAITING_FOR_FIELDS, WeatherRuntime.FieldSubmitResult.INITIAL_WINDOW_READY)); + assertEquals(WeatherRuntime.State.READY, WeatherRuntime.stateAfterSubmit(WeatherRuntime.State.READY, WeatherRuntime.FieldSubmitResult.DUPLICATE)); + } + @Test public void clearAndDisableUseSuccessfulCoreResult() { + assertEquals(WeatherRuntime.State.WAITING_FOR_FIELDS, WeatherRuntime.stateAfterClear(WeatherRuntime.State.READY, true)); + assertEquals(WeatherRuntime.State.DISABLED, WeatherRuntime.stateAfterDisable(true)); + assertEquals(WeatherRuntime.State.ERROR, WeatherRuntime.stateAfterDisable(false)); + } +} diff --git a/platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/particle/ParticleCoreLayerValidationActivity.kt b/platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/particle/ParticleCoreLayerValidationActivity.kt index 25c28a935..83423b1be 100644 --- a/platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/particle/ParticleCoreLayerValidationActivity.kt +++ b/platform/android/MapLibreAndroidTestApp/src/main/java/org/maplibre/android/testapp/activity/particle/ParticleCoreLayerValidationActivity.kt @@ -534,8 +534,20 @@ class ParticleCoreLayerValidationActivity : AppCompatActivity() { } private fun setParticleFloat(property: String, value: Float): Boolean { - return weatherRuntime?.setParticleVisual(property, value) == WeatherRuntime.CommandResult.ACCEPTED || - (weatherRuntime == null && maplibreMap.setStyleLayerFloatProperty(PARTICLE_LAYER_ID, property, value)) + val runtimeResult = weatherRuntime?.let { runtime -> + when (property) { + "raster-particle-particle-count" -> runtime.setParticleCount(value.toInt()) + "raster-particle-line-width" -> runtime.setParticleLineWidth(value) + "raster-particle-particle-length" -> runtime.setParticleLength(value) + "raster-particle-particle-opacity" -> runtime.setParticleOpacity(value) + "raster-particle-trail-opacity" -> runtime.setTrailOpacity(value) + "raster-particle-trail-fade" -> runtime.setTrailFade(value) + "raster-particle-speed-color-enabled" -> runtime.setParticleSpeedColorEnabled(value > 0.5f) + else -> null // Test-only direct entry retains fixture diagnostics such as time-mix. + } + } + return runtimeResult == WeatherRuntime.CommandResult.ACCEPTED || + (runtimeResult == null && maplibreMap.setStyleLayerFloatProperty(PARTICLE_LAYER_ID, property, value)) } private fun resetVisualDefaults() { diff --git a/src/mbgl/renderer/layers/render_particle_validation_layer.cpp b/src/mbgl/renderer/layers/render_particle_validation_layer.cpp index 958dea623..6504f22c9 100644 --- a/src/mbgl/renderer/layers/render_particle_validation_layer.cpp +++ b/src/mbgl/renderer/layers/render_particle_validation_layer.cpp @@ -999,6 +999,13 @@ bool RenderRasterParticleLayer::needsRepaint() const { baseImpl->visibility != style::VisibilityType::None; } +bool RenderRasterParticleLayer::needsHiddenLayerSourceCleanup(const RenderSource& renderSource) const { + if (!formalSource || !gpuResources || renderSource.baseImpl->type != style::SourceType::RasterArray) return false; + const auto& source = static_cast(renderSource); + const auto& impl = source.impl(); + return impl.hostFieldSubmission && !impl.field && !impl.nextField && !impl.timeline; +} + void RenderRasterParticleLayer::markLayerRenderable(bool willRender, UniqueChangeRequestVec& changes) { // RenderOrchestrator calls this while visiting each source. In a style with more // than one source, false can therefore be a transient per-source result, not a diff --git a/src/mbgl/renderer/layers/render_raster_particle_layer.hpp b/src/mbgl/renderer/layers/render_raster_particle_layer.hpp index f6cc87549..969c077ec 100644 --- a/src/mbgl/renderer/layers/render_raster_particle_layer.hpp +++ b/src/mbgl/renderer/layers/render_raster_particle_layer.hpp @@ -19,6 +19,7 @@ public: const std::shared_ptr&, const RenderTree&, UniqueChangeRequestVec&) override; + bool needsHiddenLayerSourceCleanup(const RenderSource&) const override; private: void transition(const TransitionParameters&) override {} diff --git a/src/mbgl/renderer/layers/render_weather_color_layer.cpp b/src/mbgl/renderer/layers/render_weather_color_layer.cpp index b33e176e7..f2464ffa0 100644 --- a/src/mbgl/renderer/layers/render_weather_color_layer.cpp +++ b/src/mbgl/renderer/layers/render_weather_color_layer.cpp @@ -138,6 +138,12 @@ void RenderWeatherColorLayer::evaluate(const PropertyEvaluationParameters&) { evaluatedProperties = std::move(properties); } bool RenderWeatherColorLayer::needsRepaint() const { return isLayerRenderable() && sourceField && sourceNextField; } +bool RenderWeatherColorLayer::needsHiddenLayerSourceCleanup(const RenderSource& renderSource) const { + if (!resources || renderSource.baseImpl->type != style::SourceType::RasterArray) return false; + const auto& source = static_cast(renderSource); + const auto& impl = source.impl(); + return impl.hostFieldSubmission && !impl.field && !impl.nextField && !impl.timeline; +} void RenderWeatherColorLayer::markLayerRenderable(bool willRender, UniqueChangeRequestVec& changes) { RenderLayer::markLayerRenderable(willRender, changes); } void RenderWeatherColorLayer::layerRemoved(UniqueChangeRequestVec& changes) { resources.reset(); RenderLayer::layerRemoved(changes); } void RenderWeatherColorLayer::markContextDestroyed() { resources.reset(); } diff --git a/src/mbgl/renderer/layers/render_weather_color_layer.hpp b/src/mbgl/renderer/layers/render_weather_color_layer.hpp index d8b9a2a7e..78ae29cad 100644 --- a/src/mbgl/renderer/layers/render_weather_color_layer.hpp +++ b/src/mbgl/renderer/layers/render_weather_color_layer.hpp @@ -11,6 +11,7 @@ public: ~RenderWeatherColorLayer() override; void update(gfx::ShaderRegistry&, gfx::Context&, const TransformState&, const std::shared_ptr&, const RenderTree&, UniqueChangeRequestVec&) override; + bool needsHiddenLayerSourceCleanup(const RenderSource&) const override; private: void transition(const TransitionParameters&) override {} diff --git a/src/mbgl/renderer/render_layer.hpp b/src/mbgl/renderer/render_layer.hpp index 29a7f06e5..cd27548a0 100644 --- a/src/mbgl/renderer/render_layer.hpp +++ b/src/mbgl/renderer/render_layer.hpp @@ -109,6 +109,10 @@ public: // Returns true when an active animated layer needs another MapLibre frame. virtual bool needsRepaint() const { return false; } + // Exceptional source-driven cleanup for a hidden layer. The default keeps + // normal MapLibre hidden-layer lifecycle unchanged. + virtual bool needsHiddenLayerSourceCleanup(const RenderSource&) const { return false; } + // Returns true if layer writes to depth buffer by drawing using PaintParameters::depthModeFor3D(). virtual bool is3D() const { return false; } diff --git a/src/mbgl/renderer/render_orchestrator.cpp b/src/mbgl/renderer/render_orchestrator.cpp index 92db8441d..fc93ddbd4 100644 --- a/src/mbgl/renderer/render_orchestrator.cpp +++ b/src/mbgl/renderer/render_orchestrator.cpp @@ -443,13 +443,13 @@ std::unique_ptr RenderOrchestrator::createRenderTree( } } - // Source-driven weather unload must reach hidden layers too. Normal - // visibility only suspends drawing; an empty raster-array releases resources. + // Only weather layers that explicitly opt in may clean up after Host clear. + // Ordinary hidden layers retain MapLibre's existing lifecycle. for (auto& entry : orderedLayers) { auto& layer = entry.get(); const auto source = renderSources.find(layer.baseImpl->source); if (!layer.isLayerRenderable() && source != renderSources.end() && - source->second->baseImpl->type == style::SourceType::RasterArray) { + layer.needsHiddenLayerSourceCleanup(*source->second)) { layer.prepare({.source = source->second.get(), .imageManager = *imageManager, .patternAtlas = *patternAtlas, .lineAtlas = *lineAtlas, .state = updateParameters->transformState}); @@ -985,7 +985,7 @@ void RenderOrchestrator::updateLayers(gfx::ShaderRegistry& shaders, auto& layer = entry.get(); const auto source = renderSources.find(layer.baseImpl->source); if (!layer.isLayerRenderable() && source != renderSources.end() && - source->second->baseImpl->type == style::SourceType::RasterArray) { + layer.needsHiddenLayerSourceCleanup(*source->second)) { layer.update(shaders, context, state, updateParameters, renderTree, changes); } } diff --git a/test/style/source.test.cpp b/test/style/source.test.cpp index 8259af7e5..8dd592e61 100644 --- a/test/style/source.test.cpp +++ b/test/style/source.test.cpp @@ -68,7 +68,7 @@ std::string fixtureBytes(const std::string& fixtureID, const std::string& file) std::string localMetadata(const int index) { return "{\"schema\":\"maplibre-particle-field/v1\",\"fieldId\":\"production-t" + std::to_string(index) + "\",\"fieldType\":\"WIND\",\"displayDomain\":\"GLOBAL\",\"generation\":" + - std::to_string(index + 1) + ",\"validTime\":" + std::to_string(202609040000ULL + index * 100) + + std::to_string(index + 1) + ",\"validTime\":" + std::to_string(1704067200000ULL + index * 3600000ULL) + ",\"dataVersion\":" + std::to_string(index + 1) + ",\"bounds\":{\"west\":-180,\"south\":-85,\"east\":180,\"north\":85},\"grid\":{\"width\":16,\"height\":16},\"vector\":{\"layout\":\"interleaved-uv\",\"encoding\":\"float32-le\",\"noData\":-9999},\"payload\":{\"byteLength\":2048}}"; } @@ -301,7 +301,7 @@ TEST(Source, LocalProductionFeedSubmitsSnapshotsWithProducerTime) { ASSERT_TRUE(result) << result.message; ASSERT_TRUE(result.snapshot); EXPECT_EQ(result.snapshot->generation, static_cast(index + 1)); - EXPECT_EQ(result.snapshot->validTime, 202609040000ULL + static_cast(index) * 100); + EXPECT_EQ(result.snapshot->validTime, 1704067200000ULL + static_cast(index) * 3600000ULL); snapshots.push_back(std::move(*result.snapshot)); } for (size_t index = 1; index < snapshots.size(); ++index) { @@ -441,11 +441,18 @@ TEST(Source, HostFieldClearAndTimestampSeekAreFailClosed) { EXPECT_FALSE(source.impl().timeline); EXPECT_EQ(source.submitHostField(localMetadata(0), eastPayload), style::RasterArrayHostFieldSubmitResult::AcceptedPendingInitialWindow); EXPECT_EQ(source.submitHostField(localMetadata(1), northPayload), style::RasterArrayHostFieldSubmitResult::InitialWindowReady); - EXPECT_TRUE(source.seekRuntimeTimelineToTimestamp(202609040050ULL)); + const uint64_t t0 = 1704067200000ULL; + const uint64_t t1 = 1704070800000ULL; + EXPECT_TRUE(source.seekRuntimeTimelineToTimestamp(t0)); + EXPECT_FLOAT_EQ(source.impl().timeline->frame().mix, 0.0f); + EXPECT_TRUE(source.seekRuntimeTimelineToTimestamp(t0 + 1800000ULL)); EXPECT_FLOAT_EQ(source.impl().timeline->frame().mix, 0.5f); - EXPECT_FALSE(source.seekRuntimeTimelineToTimestamp(202609039999ULL)); + EXPECT_TRUE(source.seekRuntimeTimelineToTimestamp(t1)); + EXPECT_FLOAT_EQ(source.impl().timeline->frame().mix, 1.0f); + EXPECT_FALSE(source.seekRuntimeTimelineToTimestamp(t0 - 1)); + EXPECT_FALSE(source.seekRuntimeTimelineToTimestamp(t1 + 1)); EXPECT_TRUE(source.clearHostFields()); - EXPECT_FALSE(source.seekRuntimeTimelineToTimestamp(202609040050ULL)); + EXPECT_FALSE(source.seekRuntimeTimelineToTimestamp(t0 + 1800000ULL)); } TEST(Source, HostFieldSubmissionStyleContractCreatesEmptyIngress) { @@ -515,9 +522,9 @@ TEST(Source, HostFieldSubmissionRejectsInvalidWithoutChangingLastValidField) { style::RasterArrayHostFieldSubmitResult::RejectedAdapter); auto nonMonotonic = localMetadata(2); - const auto validTime = nonMonotonic.find("202609040200"); + const auto validTime = nonMonotonic.find("1704074400000"); ASSERT_NE(validTime, std::string::npos); - nonMonotonic.replace(validTime, std::string("202609040200").size(), "202609040050"); + nonMonotonic.replace(validTime, std::string("1704074400000").size(), "1704069000000"); EXPECT_EQ(source.submitHostField(nonMonotonic, payload), style::RasterArrayHostFieldSubmitResult::RejectedNonMonotonicSnapshot); diff --git a/test/style/style_layer.test.cpp b/test/style/style_layer.test.cpp index c8d15d29d..c1dd5de7d 100644 --- a/test/style/style_layer.test.cpp +++ b/test/style/style_layer.test.cpp @@ -193,6 +193,9 @@ TEST(Layer, WeatherColorUsesIndependentFixedOpacity) { EXPECT_FALSE(layer.setColorStops({{0.0f, {0, 0, 1, 1}}})); EXPECT_FALSE(layer.setColorStops({{0.0f, {0, 0, 1, 1}}, {0.0f, {1, 0, 0, 1}}})); EXPECT_FALSE(layer.setColorStops({{0.0f, {0, 0, 1, 1}}, {10.0f, {std::numeric_limits::quiet_NaN(), 0, 0, 1}}})); + EXPECT_FALSE(layer.setColorStops({{0.0f, {0, 0, 1, 1}}, {1.0f, {0, 0, 1, 1}}, {2.0f, {0, 0, 1, 1}}, + {3.0f, {0, 0, 1, 1}}, {4.0f, {0, 0, 1, 1}}, {5.0f, {0, 0, 1, 1}}, + {6.0f, {0, 0, 1, 1}}, {7.0f, {0, 0, 1, 1}}, {8.0f, {0, 0, 1, 1}}})); EXPECT_EQ(layer.getColorStops(), valid); } diff --git a/粒子开发记录.md b/粒子开发记录.md index eb4e35059..c3fb8b6ac 100644 --- a/粒子开发记录.md +++ b/粒子开发记录.md @@ -456,3 +456,10 @@ WeatherColorLayer 的 `ParticleGpuValidationUBO` designated initializer 补齐 ` - clear 后 Source 保持可复用但无 field；Render 线程空场路径释放 Particle State/Trail/draw、field texture 与 WeatherColor resources。OFF 不 reload style，ON 后要求重新 submit T0/T1。 - WeatherColor 支持最多 8 个 validated dynamic stops；particleColor/trailColor 独立 UBO 数据通路，不依赖 WeatherColor ramp。正常 time seek 和 visual/ramp/color 更新均不重新提交 field 或 reset simulation。 - Linux shader generator、OpenGL Core 及相关 Source/Style test translation unit 已验证；Android Gradle/APK/ADB/设备/Jest 留待后续人工验收。 + +## 2026-09-07 — STEP-057A 审计修正 + +- `WeatherRuntime` 正式 Host API 改为明确 typed 粒子外观方法，删除 public string property setter；Test App 的通用 fixture 调试仍为低层路径。 +- enable/clear/disable/submit 状态转换已幂等并可恢复，另增加既有 Android JUnit state transition 测试源码；未运行 Gradle。 +- hidden unload 改成 RasterParticle/WeatherColor renderer 的 Host-empty-source 显式 opt-in cleanup，移除对所有 hidden RasterArray layer 的全局 prepare/update。 +- timestamp 测试改用真实 epoch milliseconds，覆盖 T0、midpoint、T1、上下边界和 clear 后拒绝；WeatherColor capacity 由 Java 通过 JNI 读取 C++ `MaxWeatherColorStops`。