3.8 KiB
3.8 KiB
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（tagmaplibre-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. 必做项
- 将正式
RasterParticleLayer的speedColorEnabled默认值改为false。 - 将
ParticleGpuResources初始默认值同步为false，避免资源首次创建后、视觉属性同步前出现单帧速度着色。 - 保留 shader 中速度着色逻辑和显式 setter，不删除 Validation/Test 能力。
- 更新
Layer.RasterParticleVisualProperties回归测试：默认必须为 OFF，显式打开后仍可为 ON，再可关闭。 - 默认 OFF → 显式 ON → 再 OFF 的 Core Layer 回归语义已由定向测试源码断言覆盖；未运行测试二进制。
ParticleGpuResources初始值、RenderLayer visual-property 同步和 shader UBO 开关的静态调用链已复核。git diff --check通过。- 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 后统一验收。