MapLibreParticleLab/docs/50_Step记录/STEP-068_MapLibreParticleLab_V3-04_DIRECTION粒子推进_v1.md

STEP-068 MapLibreParticleLab V3-04 DIRECTION 粒子推进

状态：完成（CLOSED / PASS）

目标与基线

基线为 particle/main / 89c72554c5fb5cd469bdd8ba06ff4b03a1a67ff9，与 origin/particle/main 一致。实现通用 DIRECTION 向量推进及独立 renderer advectionScale，不引入任何 Wave、WeatherV2 或 provider 分支。

已完成

• RasterParticleLayer 新增 raster-particle-advection-scale 与 C++ getAdvectionScale()/setAdvectionScale()；默认 1.0，非 finite 或非正值 fail-closed。
• State fragment 与正式 line vertex 共享同一语义：分别解码 T0/T1、分量 MIX、检查有限性；DIRECTION 对混合结果归一化并乘 scale，长度 <= 1e-5 无效；VELOCITY 保留原始分量 MIX 与 magnitude。
• UBO 新增明确 advection vec4（Direction flag、scale、epsilon），C++ struct/static_assert、两份 GLSL 和 generated OpenGL header 同步。
• renderer 接受 vector VELOCITY 与 DIRECTION；scalar-only、缺 semantics 或 T0/T1 semantics 不同仍清理并 fail-closed。
• advectionScale 仅更新 renderer uniform，不上传 field texture、不重置 Timeline/State/Trail。
• C++ oracle 测试覆盖 east/north/diagonal、east/west MIX 归零、scale 改变 magnitude，以及 VELOCITY 不归一化且不消费 scale；Layer 测试覆盖默认、set/get 与非法值。

禁止范围确认

未修改 Android、JNI、Java/Kotlin、RN、WeatherV2、NavSea、Timeline/Playback/Runtime Window、STEP-062 用户修改或历史无关文件；未执行 Gradle、AAR/APK/ADB 或 Jest。

验证

• node shaders/generate_shader_code.mjs：PASS（输出节流）。
• 第一轮受影响对象 render_particle_validation_layer.cpp.o、raster_particle_layer.cpp.o、style_layer.test.cpp.o：PASS（输出节流；发生在新增 CPU oracle 后的最终重编译前）。
• 既有过滤测试 Layer.RasterParticle*:Source.ParticleFieldV3*：PASS（输出节流；发生在新增 CPU oracle 后的最终重链前）。
• 最终受影响精确对象：render_particle_validation_layer.cpp.o、render_weather_color_layer.cpp.o、raster_particle_layer.cpp.o、source.test.cpp.o、style_layer.test.cpp.o：PASS。
• ninja -C build-linux-opengl -j3 mbgl-test mbgl-test-runner：PASS，完整目标重编译/重链完成（本轮约 899.5 秒）。
• STEP-068 相关过滤测试 Source.ParticleFieldV3*:Layer.RasterParticle*：8/8 PASS；其中包含 DIRECTION east/north/diagonal、MIX northeast、opposite fail-closed、VELOCITY 不归一化及 advectionScale 属性。
• git diff --check：PASS。
• shader generator：此前本 Step 已 PASS；WeatherColor UBO 最小修复未修改 shader/generator 输入，无需再次生成。

2026-09-11 全量 Linux 重编译发现的 UBO 初始化遗漏

全量 Linux 重编译在 src/mbgl/renderer/layers/render_weather_color_layer.cpp:108 以 -Wmissing-field-initializers 发现 ParticleGpuValidationUBO::advection 新增后 WeatherColor 的 designated aggregate initializer 未同步。已仅在该 color-only pass 显式补入安全中性值 {Direction flag=0, scale=1, epsilon=1e-5, reserved=0}；WeatherColor 不执行 advection，色场取样和颜色路径不变。

搜索确认 C++ 中仅有两个 ParticleGpuValidationUBO 聚合初始化器：Particle renderer 已初始化 advection，WeatherColor 为本次唯一遗漏。此项修复后的 shader generator 不需要重跑（未修改 shader/generator 输入）。修复后的 WeatherColor 精确对象编译与 git diff --check 均已 PASS；编译日志按输出节流保存。随后外部终端完成完整 mbgl-test / mbgl-test-runner 重编译与重链并 PASS。

独立既有测试问题与下一步

全量目标构建 PASS 后，额外扩大过滤范围时发现当前 HEAD 已存在的 Layer.WeatherColorUsesIndependentFixedOpacity 断言错误：测试先成功调用 setColorStops({{-2,...},{3,...}}) 改变状态，最后却仍断言等于更早的 {0,10,20}。git show HEAD:test/style/style_layer.test.cpp 已确认该错误在 STEP-068 开工前即存在，且本 Step 对该测试的 diff 只有新增 RasterParticle 测试。为保持任务隔离，本 Step 不修改该既有 WeatherColor 测试，也不把它作为 DIRECTION 关闭门槛。

STEP-068 相关实现、精确对象、完整 Linux 目标重链、8 个相关过滤测试与 git diff --check 均已通过，因此本 Step 正式 CLOSED / PASS。Android Gradle/AAR/APK/ADB 与 Jest 仍按任务要求未执行。下一步进入 V3-05：Android/JNI/RN generic v2 multi-plane ingress。

Git 收尾

• 实现提交：f3c33c67275b24f61b80924abbb9d10d68b2cb7c
• commit message：feat: add direction particle advection
• push：成功
• 远端分支：origin/particle/main
• 实现提交 push 后：HEAD == origin/particle/main == f3c33c67275b24f61b80924abbb9d10d68b2cb7c
• STEP-062 两处用户修改及历史 untracked/build/cache/tgz 均未暂存、未提交。