From bc6b8dd84b4c10e5263d61832661508c02d84d88 Mon Sep 17 00:00:00 2001 From: tei Date: Sat, 19 Sep 2026 21:58:48 +0900 Subject: [PATCH] fix: disable particle speed color by default --- ...084_正式粒子速度着色默认关闭与红头修复_v1.md | 50 +++++++++++++++++++ .../render_particle_validation_layer.cpp | 4 +- .../layers/raster_particle_layer_impl.hpp | 4 +- test/style/style_layer.test.cpp | 4 +- 粒子开发记录.md | 6 +++ 5 files changed, 65 insertions(+), 3 deletions(-) create mode 100644 docs/50_Step记录/STEP-084_正式粒子速度着色默认关闭与红头修复_v1.md diff --git a/docs/50_Step记录/STEP-084_正式粒子速度着色默认关闭与红头修复_v1.md b/docs/50_Step记录/STEP-084_正式粒子速度着色默认关闭与红头修复_v1.md new file mode 100644 index 000000000..03fd11fa1 --- /dev/null +++ b/docs/50_Step记录/STEP-084_正式粒子速度着色默认关闭与红头修复_v1.md @@ -0,0 +1,50 @@ +# STEP-084 正式粒子速度着色默认关闭与红头修复 v1 + +状态：`完成（等待 STEP-085 后由 RDC 统一执行 Native/真机验收）` + +## 1. 目标 + +修复 NavSea 天气正式粒子在 Android/iOS 均出现橙红色“头部”的问题。正式 `RasterParticleLayer` 默认应严格使用宿主显式提供的 `particleColor`；速度着色只作为显式 opt-in 能力保留，不再作为正式粒子的默认行为。 + +## 2. 基线 + +- 机器：Mac-mini-tei.lan。 +- 工作仓库：`/Users/tei/dev/MapLibreParticleLab-step084`，独立 worktree，避免触碰主 Mac 工作树既有 dirty/untracked。 +- branch：`step/084-particle-speed-color-default-off`。 +- start commit：`91d4859121afef98e05efac923797b31835a49df`（tag `maplibre-particle/rn/13.4.1-particle.7`）。 +- Integration repo 已同步并核对 `main`；本修正不改变 RN 公共 API、QBIN/Field contract 或 NavSea/Particle 责任边界。 + +## 3. 根因 + +正式 fragment/Metal shader 在 `speedColorEnabled=true` 时，会对当前粒子段覆盖 `particleColor`，使用内置速度色带；高速端为橙红色。`RasterParticleLayer::Impl` 当前默认值为 `true`，因此 Host 未显式设置该属性时，Android OpenGL 与 iOS Metal 都会出现同样的红头。 + +## 4. 必做项 + +- [x] 将正式 `RasterParticleLayer` 的 `speedColorEnabled` 默认值改为 `false`。 +- [x] 将 `ParticleGpuResources` 初始默认值同步为 `false`，避免资源首次创建后、视觉属性同步前出现单帧速度着色。 +- [x] 保留 shader 中速度着色逻辑和显式 setter，不删除 Validation/Test 能力。 +- [x] 更新 `Layer.RasterParticleVisualProperties` 回归测试：默认必须为 OFF，显式打开后仍可为 ON，再可关闭。 +- [x] 默认 OFF → 显式 ON → 再 OFF 的 Core Layer 回归语义已由定向测试源码断言覆盖；未运行测试二进制。 +- [x] `ParticleGpuResources` 初始值、RenderLayer visual-property 同步和 shader UBO 开关的静态调用链已复核。 +- [x] `git diff --check` 通过。 +- [x] scoped commit 并 push 到 `origin/particle/main`（commit 与远端确认见本轮最终交付）。 +- [ ] Mac Metal 精确编译、Android Native/AAR 编译与 Android/iOS 设备验收：`BUILD_NOT_RUN_BY_CODEX — WAITING_FOR_RDC`。任务书要求与 STEP-085 性能修复合并验收，故本 Step 不单独声称平台 PASS。 + +## 5. 禁止范围 + +- 不修改 QBIN V4、FieldProfile、Runtime Window、时间插值或天气数据。 +- 不增加 iOS/Android 专用公共协议，不增加 RN 平台分叉。 +- 不修改 NavSea。 +- 不删除 speed-color 能力；只改变正式层默认值。 +- 不执行 Android Gradle/AAR/APK 编译、安装或 ADB 操作；Android 构建仍由用户手工执行。 + +## 6. 验收语义 + +默认情况下 `current ? particleColor : trailColor` 选择完成后，不再进入 `particleSpeedColor(...)` 覆盖分支；只有调用方显式打开 speed-color 时才允许速度色覆盖当前粒子段。由于 OpenGL GLSL 与 Metal shader 共用同一 `speedColorEnabled`/UBO 语义，本修正应在重新构建各平台 Native 后同时生效。 + +## 7. Codex 静态收尾 + +- 远端 `origin/particle/main` 在本 Step 开始时与 start commit 一致；现有 dirty 仅含任务书列出的三处源码/测试修改及本 Step 记录，未混入 STEP-085 性能代码。 +- `RasterParticleLayer::Impl` 默认值与 `ParticleGpuResources` 的资源首帧默认值均为 `false`；显式 setter 及 shader speed-color 分支保持不变。 +- `Layer.RasterParticleVisualProperties` 明确覆盖 default OFF、set ON 与 set OFF，因此正式宿主未设属性时不再选择内置速度色带，诊断/显式 opt-in 仍然可用。 +- 未执行任何 Native 编译、链接、artifact、Gradle、ADB、iOS 安装或真机工作；这些项目由 RDC 在 STEP-085 后统一验收。 diff --git a/src/mbgl/renderer/layers/render_particle_validation_layer.cpp b/src/mbgl/renderer/layers/render_particle_validation_layer.cpp index 05d3a6bb2..07d2c26d0 100644 --- a/src/mbgl/renderer/layers/render_particle_validation_layer.cpp +++ b/src/mbgl/renderer/layers/render_particle_validation_layer.cpp @@ -361,7 +361,9 @@ public: float trailOpacity = 1.0f; float trailFade = 0.92f; float advectionScale = 1.0f; - bool speedColorEnabled = true; + // Match the formal layer default so a newly allocated resource cannot emit + // one speed-colored frame before evaluated visual properties synchronize. + bool speedColorEnabled = false; std::array particleColor{0.08f, 0.55f, 1.0f, 1.0f}; std::array trailColor{1.0f, 1.0f, 1.0f, 1.0f}; uint8_t fixtureMode = 255; diff --git a/src/mbgl/style/layers/raster_particle_layer_impl.hpp b/src/mbgl/style/layers/raster_particle_layer_impl.hpp index 9531f4f78..79d232e22 100644 --- a/src/mbgl/style/layers/raster_particle_layer_impl.hpp +++ b/src/mbgl/style/layers/raster_particle_layer_impl.hpp @@ -28,7 +28,9 @@ public: // scale is deliberately independent from field metadata and only applies // when VectorSemantics is Direction. float advectionScale = 1.0f; - bool speedColorEnabled = true; + // Formal particles honor the explicit particleColor by default. Speed-based + // head coloring remains available as an explicit opt-in diagnostic mode. + bool speedColorEnabled = false; std::array particleColor{{0.08f, 0.55f, 1.0f, 1.0f}}; std::array trailColor{{1.0f, 1.0f, 1.0f, 1.0f}}; DECLARE_LAYER_TYPE_INFO; diff --git a/test/style/style_layer.test.cpp b/test/style/style_layer.test.cpp index 6064802ec..2d90c3249 100644 --- a/test/style/style_layer.test.cpp +++ b/test/style/style_layer.test.cpp @@ -143,8 +143,10 @@ TEST(Layer, RasterParticleVisualProperties) { EXPECT_FLOAT_EQ(1.0f, layer.getParticleOpacity()); EXPECT_FLOAT_EQ(1.0f, layer.getTrailOpacity()); EXPECT_FLOAT_EQ(0.92f, layer.getTrailFade()); - EXPECT_TRUE(layer.isSpeedColorEnabled()); + EXPECT_FALSE(layer.isSpeedColorEnabled()); + layer.setSpeedColorEnabled(true); + EXPECT_TRUE(layer.isSpeedColorEnabled()); layer.setLineWidth(4.0f); layer.setParticleLength(0.030f); layer.setParticleOpacity(0.45f); diff --git a/粒子开发记录.md b/粒子开发记录.md index f6129aec7..eeac62bbf 100644 --- a/粒子开发记录.md +++ b/粒子开发记录.md @@ -1,5 +1,11 @@ # 粒子开发记录 +## 2026-09-19 — STEP-084 正式粒子速度着色默认关闭 + +- 正式 `RasterParticleLayer` 与初始 `ParticleGpuResources` 的 `speedColorEnabled` 默认值均改为 `false`，使未显式配置时严格使用宿主 `particleColor`，避免内置高速橙红色带在首次资源创建前覆盖粒子颜色。 +- speed-color shader 分支、公开 Core setter 与 Android Validation UI 显式开关均保留；`Layer.RasterParticleVisualProperties` 覆盖默认 OFF → 显式 ON → 再 OFF。 +- Codex 仅完成源码静态审计和 `git diff --check`，未执行 Native 编译、链接、artifact、设备或真机验证；颜色验收将与 STEP-085 renderer 性能修复由 RDC 统一进行。 + ## 2026-08-27 — STEP-000 - 建立正式 Ubuntu MapLibreParticleLab 工作目录。 - MapLibre core：18545ca10d296704b2cba675b182ff2c8da24588