MapLibreParticleLab/docs/报告/40_01_Android正式粒子Trail显示修复_Codex完成报告_v1.md

40-01 Android 正式粒子 Trail 显示修复 Codex 完成报告 v1

1. 结论

已修复“simulation 正常推进但正式 RasterParticle 屏幕主体静止”的 Composite 显示路径。40-01 仍为 WAITING_MANUAL_VALIDATION；未运行 Android Gradle、ADB 或真机。

2. 实际根因

RenderRasterParticleLayer 的 State A/B 与 Trail A/B 已按日志正常推进，Trail pass 也读取当前 State write texture。但是 particle_gpu_validation 的 Composite 只把 u_previous（Trail）的 RGB 折算为 alpha intensity，最终 RGB 仍无条件输出 30-03 的蓝色 stripe 和黄色 anchors；并且 ACTIVE Composite 的 legacy stripe frame 参数为零。于是 GPU 粒子没有成为可见输出。

3. 修复

• ParticleGpuResources::formalDisplay 只在正式 RasterParticleLayer 建立资源时设为 true，并经现有 UBO 的 u_mask.z 传入 shader；不增加第二套 simulation。
• FORMAL_PARTICLE Composite 以当前 Trail texture RGB 为最终 premultiplied color，并以 Trail intensity 决定 alpha。uniform-east 的 State 位置经 Trail 进入 Composite，因此屏幕应可见连续向 east 的 marker/trail 运动；STATIC/FrozenComposite 继续采样最后一个 Trail read slot。
• LEGACY VALIDATION DISPLAY 保留原有 30-03 stripe、anchors、mask、world-wrap 与 antimeridian 分支，不受正式显示模式影响。
• shader 源唯一为 shaders/particle_gpu_validation.fragment.glsl；使用 node shaders/generate_shader_code.mjs 生成 include/mbgl/shaders/gl/particle_gpu_validation.hpp。生成器会同步规范化 src/mbgl/shaders/shader_source.cpp，已保留该生成物以保证二次运行无差异。
• 增加一次性 displayMode=FORMAL_PARTICLE|VALIDATION 日志，以及低频 trailStateSource / compositeTrailSource 日志，诊断 State→Trail→Composite 的正式数据流。

未改变 Offline fixture adapter、RasterArraySource、RasterParticleLayer、field/NoData、State/Trail ping-pong、mask、ACTIVE/STATIC lifecycle、zero-step bootstrap、FrozenComposite、rotation resource recreation、world wrap、antimeridian 或 RasterArray source RenderItem contract。

4. 静态验证

• Linux OpenGL：render_particle_validation_layer.cpp.o 精确编译 PASS。
• 相关现有 C++：test/style/source.test.cpp.o 精确编译 PASS。
• shader generator：连续运行两次后 particle_gpu_validation.hpp 与 shader_source.cpp 哈希一致，PASS。
• clang-format --dry-run --Werror（受影响 C++）和 git diff --check：PASS。
• 未运行完整 mbgl-test：该 target 在本 build tree 仍需 312 个对象，属于与本次 shader 显示修复无关的广泛构建，未把未执行测试描述为 PASS。

5. 后续人工验收

用户下一轮仅验收 GLOBAL + ACTIVE + uniform-east：正式 RasterParticle 必须肉眼清楚、连续地向 east 移动。通过后再测试 STATIC、uniform-north、Rotation 与 T1-T12。

6. Git 收尾

最终代码修复 commit：c8e1f942ebd5c5447990bb4fe001fdaf234fd740（fix: display formal particle trails）。push 成功后，remote branch 与最终 origin/particle/main HEAD 在交付结果中记录。