MapLibreParticleLab/docs/报告/STEP-055_Android真实WeatherV2风场综合可视化_Codex完成报告_v3.md

STEP-055 真实 WeatherV2 风场 Particle State 纹理精度修复 Codex 完成报告 v3

基线、范围与根因

• Starting HEAD：37c9aa31da1d2b3495c8802e6fd2f6b999562b06
• 分支：particle/main
• 状态：IMPLEMENTED / WAITING_ANDROID_VALIDATION

真实 Weather State shader 已计算非零 m/s→Web Mercator 位移且 State A/B ping-pong 持续，但 State RG world coordinate 写回被共用的 RGBA8/UnsignedByte target 量化。1/255≈0.00392 world 大于 Android 已观测的 0.000003–0.000008 world 单步位移，故每步无法积累，是“simulation 在跑但粒子静止”的确定性根因。

修改

• render_particle_validation_layer.cpp：State A/B 初始创建与 particleCount replacement 均为 TextureChannelDataType::Float；Trail A/B 仍为 UnsignedByte。创建函数显式接收 data type/kind，并在 FBO 创建失败时 log error、拒绝 target，无 UByte fallback。
• render_target.hpp/.cpp：新增最小 RenderTarget::isRenderable() forwarding，使 target 创建即可验证当前后端实际 FBO。
• particle_gpu_validation.fragment.glsl：只修正 RG 为 Web Mercator world position 的注释；未改 m/s conversion 或 visualSpeedScale=6000。
• 生成的 OpenGL shader header 同步更新。

Android OpenGL 既有实现已经支持 Float：gl::Context::createRenderTarget → RenderTarget → gl::OffscreenTexture → Texture2D(RGBA, Float) → GL_RGBA32F/GL_FLOAT → glFramebufferTexture2D → checkFramebuffer()。因此未修改 Android/OpenGL backend；若设备 FBO 不完整，现有 isRenderable() 返回失败，Particle target 记录具体 Float failure 并 fail-closed。

运行时日志包括每个成功 CREATE_SUCCESS，以及 State/Trail pair summary：stateAType=Float stateBType=Float trailAType=UnsignedByte trailBType=UnsignedByte。这基于已实际完成 backend FBO validation，而非仅打印请求值。

架构保护

未修改 canonical Field、U/V 语义、STEP-054 assets、Host submission、Timeline、Runtime Field Window、WeatherColorLayer 或 6000 visual speed scale。没有新增 GPU readback、网络、Provider、React Native、Jest 或 Android UI 变化。

验证

• node shaders/generate_shader_code.mjs：PASS；generated OpenGL header 与 fragment source 同步。
• Linux OpenGL CMake 精确编译：render_target.cpp、render_particle_validation_layer.cpp、gl/offscreen_texture.cpp、gl/texture2d.cpp：PASS。
• 现有非 Jest test/style/style_layer.test.cpp：以相同 OpenGL CMake 参数精确编译 PASS；本轮没有适合脱离实际 GL context 的 Float FBO 单元 runner，因此 FBO runtime 完整性保留 Android 实机检查。
• git diff --check：PASS（最终提交前将再次执行）。
• Android Gradle/APK/ADB/App/设备：未执行。
• Jest：未执行，未修改。

人工验收说明：v3。第一门槛是 Timeline Pause 下 Float State 粒子连续运动；若仍不动，不调 6000，转入后续 GPU State 读回诊断。

Git

功能提交：f0f0623e06a3237e3f667dccc1ee451b98e9be57（fix: use float particle state targets）。

功能提交已成功 push 至 origin/particle/main。本报告的 Git 元数据补充将以独立文档提交完成；该文档提交不会改变功能实现。用户既有未跟踪文件未触碰、未 stage。

最终状态：IMPLEMENTED / WAITING_ANDROID_VALIDATION。