40-05 Android OpenGL 正式粒子视觉与运行时渲染控制 — Codex 完成报告

日期：2026-09-03 状态：CLOSED / PASS

结果

40-05 / STEP-046 已完成代码、Android 验收入口与用户手工 Android OpenGL 最终验证，正式关闭为 CLOSED / PASS。

实施提交：e48fa087e01e9710c5d0c18ab062726226bbb6bd（feat: add particle visual runtime controls）。Android APK 编译、copy、安装、实体机/虚拟机操作及完整 logcat 抓取均由用户完成；本次文档收尾未重新执行 Android Gradle、ADB 或 Jest。

A. 正式方向 geometry

RenderRasterParticleLayer 的正式 full draw 不再画固定蓝色 point。每个 State texel 创建两个静态 line vertices；vertex shader 读取当前 State write、T0/T1 Field，并以 timeMix 取得最终 GPU velocity。方向由 vec2(u, -v) 在 Mercator 边界生成，所以继续遵守 U=east-positive、V=north-positive、dy=-v。没有 CPU 每粒子 direction/color、GPU readback、第二 simulation 或 Overlay。

B/C. 视觉属性与速度颜色

Core RasterParticleLayer 具有 line width、streak length、particle/trail opacity、trail fade、speed-color enabled 的强类型 setter 和 style property 支持。速度色使用 shader 内蓝→绿→橙最小 ramp，输入是最终插值后的 magnitude；NoData/invalid velocity 在 vertex shader 直接不绘制。Legacy ParticleValidationLayer 的旧验证显示没有被改为正式视觉路径。

D. Android runtime 控制

Android Test App 通过既有 setStyleLayerFloatProperty() boolean JNI bridge 调用 Core 强类型 setter，不建立 Java RasterParticleLayer peer。请求失败时 Kotlin 不写入本地 visual state；成功后才更新状态栏。新增控制：VISUAL DEFAULT、SIZE ±、LENGTH ±、OPACITY ±、TRAIL ±、FADE ±、COLOR，以及直接 VORTEX 与 256K capacity 入口。

E. 观测和回归

资源日志现在明确区分 particleDrawCount（粒子数）与 streakVertexCount（两端点数）。visual property 变化输出一次结构化摘要，含 Field upload/reset counters 与 resource identity；没有每粒子或每帧日志，也没有虚构 GPU timer。

保持不变

40-02 T0/T1 GPU interpolation 和 MIX property-only。
40-03 N State texels -> N actual particle draw 与已验证 capacity >=1,048,576。
40-04 Runtime Field A/B→B/C→C/D、OLD_T1→NEW_T0 reuse、Duplicate NOOP、候选耗尽 fail-closed。
State/Trail ping-pong、STATIC frozen composite、mask reuse、camera/world wrap/antimeridian 和 rotation lifecycle。

视觉参数改变预期 FIELD_UPLOAD delta=0、SIMULATION_RESET delta=0、STYLE_LOAD delta=0；本实现没有 visual GPU resource rebuild。

已执行验证

shader generator 连续两次运行：PASS，OpenGL generated header 已同步。
Linux OpenGL 精确对象编译：
- CMakeFiles/mbgl-core.dir/src/mbgl/style/layers/raster_particle_layer.cpp.o
- CMakeFiles/mbgl-core.dir/src/mbgl/renderer/layers/render_particle_validation_layer.cpp.o
- test/CMakeFiles/mbgl-test.dir/style/style_layer.test.cpp.o
- 结果：PASS。
C++ RasterParticleVisualProperties 最小测试已加入并成功编译。
clang-format、git diff --check：PASS。

未执行：Android Gradle、ADB、安装、真机、Jest。

Android 最终验收结果

T1：PASS。UNIFORM EAST、UNIFORM NORTH、VORTEX 正式 streak 显示和方向均正常。
T2：PASS。VIS DEFAULT、SIZE ±、LENGTH ±、OPACITY ±、TRAIL ±、FADE ±、COLOR 均经正式 Runtime Property 生效；未描述或实现为 Field reload / simulation rebuild。
T3：PASS。T0 EAST/T1 NORTH、MIX 0/50/100 和 speed color 正常；MIX 保持 property-only，没有 Field Window reload 或 simulation reset。
T4：PASS。40-04 冻结的 Runtime Field Window 语义无回归：A/B→B/C→C/D、OLD_T1 -> NEW_T0 reuse、仅上传新 T1、Duplicate NOOP、fail-closed、Style 不重载、simulation 不无意义 reset、Trail 不无意义清空均通过。
T5：PASS。pan、zoom、bearing/camera、DATELINE、WORLD WRAP 未见正式粒子与地图组合异常。
T6：PASS。DISABLE/ENABLE 和屏幕/生命周期恢复后粒子自动恢复，无需额外按钮。
T7：PASS。GLOBAL、OCEAN A、OCEAN B 保持既有 mask 语义。
T8：PASS。256、1K、4K、16K、64K、256K、1M 均实际运行；1M 在正式 streak + speed color 路径上无 crash、黑屏、Renderer 中断、明显资源错误或结构性 full-particle-draw 失败。

当前 viewport 中 4K 以上会因高密度 streak + Trail 而接近铺满画面。这是 Validation 可读性现象：256/1K 用于视觉检查，4K 以上主要用于容量和稳定性，不构成功能失败，也不需要为此改 Renderer 或重新编译 APK。1M 仍仅代表当前验证设备上已验证的容量，不是理论最大值、默认产品数量或全设备保证。

logcat 中 TimeStats: RenderEngineTimes are already at its maximum size[64] 是 Android/RenderEngine/虚拟机侧噪声。用户同时观察到粒子 Renderer 连续执行 State -> Trail -> Composite 并保持 hazard=SAFE，未有对应 crash 或中断；该信息不构成 STEP-046 Renderer FAIL。

Git 收尾

本报告随文档收尾提交并推送到 origin/particle/main。用户既有未跟踪任务书和审查 diff 不纳入提交。

最终结论

未发现阻塞性问题。40-05 / STEP-046：CLOSED / PASS。

范围外

未实现 WeatherColorLayer、真实天气 HTTP/GRIB/provider、React Native、Vulkan、iOS/Metal、生产 mask、粒子箭头/旋转或 APK ZIP 技术债。

5.5 KiB Raw Permalink Blame History Unescape Escape