3.7 KiB
STEP-068 MapLibreParticleLab V3-04 DIRECTION 粒子推进 Codex 完成报告
结论：CLOSED / PASS。
已完成
生产代码限定在 RasterParticleLayer Core 属性、Particle renderer、Particle shader/UBO 和 generated OpenGL shader header。DIRECTION 采用 T0/T1 U/V 分量插值后再归一化；零或近零、NaN/Inf 混合向量 fail-closed。advectionScale 默认 1.0，必须 finite 且大于零，仅作用于 DIRECTION 的推进长度。VELOCITY 没有归一化，也不读取该 scale，保持既有 U east/V north 与 Web Mercator 位移数学。
State 与 line vertex 都使用相同的 resolved advection 语义。renderer 仍拒绝 scalar-only、缺 semantics 和 T0/T1 semantics mismatch；字段内容 reuse、T0/T1/MIX、rollover、lifecycle 与 trail 没有重写。变更 scale 不会重传 field texture 或重建 simulation/trail。
增加 C++ Layer 属性测试，以及 provider-neutral CPU oracle 测试：东、北、斜向、T0 east/T1 north/MIX 0.5 的 northeast、反向归零 invalid、scale 仅改 Direction magnitude，和 VELOCITY 保持未归一化。
验证结果
- shader generator：PASS。
- 最终受影响精确对象（Particle/WeatherColor renderer、RasterParticle style、source/style tests）：PASS。
ninja -C build-linux-opengl -j3 mbgl-test mbgl-test-runner：PASS，完整目标重编译/重链完成。- STEP-068 相关过滤测试
Source.ParticleFieldV3*:Layer.RasterParticle*：8/8 PASS。 git diff --check：PASS。- Android Gradle/AAR/APK/ADB、Jest：未执行，任务明确禁止。
2026-09-11 全量 Linux 重编译遗漏修复
外部全量 Linux 重编译报告 render_weather_color_layer.cpp:108 的
-Wmissing-field-initializers：共享 ParticleGpuValidationUBO 增加 advection 后，
WeatherColor 的聚合初始化未同步。本次只显式初始化该字段为 {0, 1, 1e-5, 0}：
Direction flag 关闭、scale 为单位值，且 WeatherColor 不消费 advection，因此不影响
色场。审计所有 C++ 聚合初始化器后，Particle renderer 已完整初始化；WeatherColor
是唯一遗漏。
本次未改 shader 输入，不需为该 C++ 初始化修复重新运行 shader generator。修复后的
WeatherColor 精确对象编译和 git diff --check 均 PASS（编译输出已限流保存）；随后
外部终端完成 mbgl-test / mbgl-test-runner 完整目标重编译与重链并 PASS。
独立既有测试问题、风险与下一步
扩大过滤范围时，当前基线自带的 Layer.WeatherColorUsesIndependentFixedOpacity 暴露一个与 STEP-068 无关的测试断言错误：测试已成功把 stops 改为 {-2,3}，最后却断言仍等于旧的 {0,10,20}。通过 git show HEAD:test/style/style_layer.test.cpp 已确认该逻辑在 STEP-068 前就存在；本 Step 不修改该旧测试，避免把无关修复混入 DIRECTION 实现。
STEP-068 自身相关 8 个测试全部 PASS，完整 Linux 目标也已 PASS，因此可以关闭。剩余平台风险保留到后续综合阶段：Android/Vulkan 与最终设备 shader driver 仍未在本 Step 验证。下一步为 V3-05 Android/JNI/RN generic v2 multi-plane ingress；仍不在此处引入 WeatherV2/NavSea 业务逻辑。
Git 交付
- 主实现 commit：
f3c33c67275b24f61b80924abbb9d10d68b2cb7c - commit message：
feat: add direction particle advection - push result：成功
- remote branch：
origin/particle/main - 主实现提交推送后确认：
HEAD == origin/particle/main == f3c33c67275b24f61b80924abbb9d10d68b2cb7c - 本报告随后仅追加 Git 交付记录并进行独立文档收尾提交；主实现 commit 保持不变。
- 未纳入 STEP-062 用户修改及历史无关 untracked/build/cache/tgz。